Polish documentation #77
Conversation
doc/source/api/box.rst
Outdated
There was a problem hiding this comment.
Although lammpsio is broken up into separate Python files, the documented API all runs directly through the main namespace, like lammpsio.Box, and there aren't really that many different classes. Hence, I would recommend reorganizing all this into one "API" page (that you link into the main toc, no need to separate a User Guide and API Reference). Then, use autosummary with the toctree directive to autogenerate the documentation for our classes. You can check relentless for an example of doing this!
There was a problem hiding this comment.
How would we handle the Topology module? We don't bring that in to the main namespace.
There was a problem hiding this comment.
I think I would make a separate section & autosummary for topology, and refer to the classes by their fully qualified names to make that clear (lammpsio.topology.Bonds, etc.)
| @@ -50,6 +65,18 @@ def cast(cls, value): | |||
| :class:`Box` | |||
| A simulation box matching the array. | |||
|
|
|||
| Examples | |||
There was a problem hiding this comment.
This is great, I'd like to see more examples like this and have them run as unit tests with sybil.
Additionally, review all documentation for proper cross-referencing of classes, attributes, etc. I was probably rather lazy / inconsistent in doing so. Generally, single ticks get a cross reference, but double ticks make a verbatim code.
You may be able to also omit use of :class: everywhere to make this cross referencing simpler. I think that is not necessarily needed in modern sphinx.
|
@mphoward, one thing that we need to do is enable a discussion page in the repository for users to reach out if they need help. Can you do that when you have some time? |
|
These should be enabled now! |
|
@mayukh33, sybil will need to be added to the |
for more information, see https://pre-commit.ci
This PR should fully address Issue #9.