Automatic build of docs for compile command
#64
Conversation
(for re-use by other parts of the code)
…li into compile-docs
Codecov Report
@@ Coverage Diff @@
## main #64 +/- ##
==========================================
Coverage 100.00% 100.00%
==========================================
Files 51 57 +6
Lines 2143 2279 +136
==========================================
+ Hits 2143 2279 +136
Continue to review full report at Codecov.
|
|
This is ready for review and comment. I will leave it open for at least 30 hours, merging no earlier than Tue 02 Nov 22:00 GMT (18:00 my local). CodeClimate has a complaint about This code in this PR is mainly intended to get the infrastructure ready so that future PRs can fill in additional details needed to create the detailed documentation. Just as an example, using the following as part of a config file: volume:
header: Volumes
description: |
State and interface definitions in OpenPathSampling are (hyper)volumes
in phase space. Use these tools to define states and the substituent
volumes that comprise them.The current code generates the following RST (from the command .. _compiling--volume:
Volumes
=======
State and interface definitions in OpenPathSampling are (hyper)volumes
in phase space. Use these tools to define states and the substituent
volumes that comprise them.
.. contents:: :local:
.. _volume--cv-volume:
cv-volume
---------
* **type** - type identifier; must exactly match the string ``cv-volume`` (required)
* **name** (*string*) - name this object in order to reuse it
* **cv** (:ref:`cv <compiling--cv>`) - CV that defines this volume (required)
* **lambda_min** (None) - Lower bound for this volume (required)
* **lambda_max** (None) - Upper bound for this volume (required)
.. _volume--intersection:
intersection
------------
* **type** - type identifier; must exactly match the string ``intersection`` (required)
* **name** (*string*) - name this object in order to reuse it
* **subvolumes** (list of :ref:`volume <compiling--volume>`) - List of the volumes to intersect (required)
.. _volume--union:
union
-----
* **type** - type identifier; must exactly match the string ``union`` (required)
* **name** (*string*) - name this object in order to reuse it
* **subvolumes** (list of :ref:`volume <compiling--volume>`) - List of the volumes to join into a union (required)
I'm very much open to changing the details of the RST in the future if that improves presentation; my main priority here is to get something that can be useful for users and will be easy for us to maintain. |
dwhswenson
changed the title
compile commandcompile command
sroet
left a comment
sroet
left a comment
There was a problem hiding this comment.
one pylint complaint and leftover TODO; LGTM otherwise
Co-authored-by: Sander Roet <sanderroet@hotmail.com>
2 participants
This creates automatic documentation generation tools for the input file format used by the
compilecommand. The code to do this will not be considered part of the API, because there may be significant changes in it over time. However, documenting the functionality available in thecompilecommand is essential before the v0.3 release where we announce the availability of this command.One of the major goals here is to keep documentation and source together, in order to ensure that new functionality is automatically documented online. This is done by keeping a
descriptionstring in plugins, which can then be used in the docs.This PR will mainly provide the infrastructure for building docs. Many plugins still need descriptions to be filled in; this will occur in a future PR.