Document one class per html page and list all inherited members. #1952
Conversation
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
To do this, we need to be able to import hoomd from the source directory. I prefer not to add additional dependencies (Mock), so we include manually prepared mock files to make the import possible.
Return a non-zero exit value so that pre-commit will fail.
joaander
added
validate
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
Description
pre-commit now runs the script
generate-toctree.pywhich importshoomdand walks the namespace (which is now defined by__all__variables in each module). It generates one.rstfile per module and class. The module files are always generated. Class files are only generated if they do not exist yet - allowing customization of the class files. Developers should add new classes to__all__and then they will automatically appear in the documentation after running pre-commit.Inspired by
rustdoc, each class page now explicitly lists all of its inherited members. This brief list repeats only the first line of the documentation for each member and provides a "Read more..." link back to the original. To implement this, he top level public-facing classes now define_doc_inherited. Subclasses include this string in__doc__and append to it if they define members that are later inherited.Motivation and context
Prior to this change, the documentation for long modules (such as
md.pair) was difficult to navigate. Users have also expressed confusion over the class hierarchy and found it difficult to navigate up the tree and determine what methods are available. The new system is also more automated than the previous and reduces the amount of developer effort to add new classes.Resolves #1905
Resolves #1914
How has this been tested?
Checklist:
sphinx-doc/credits.rst) in the pull request source branch.CHANGELOG.rstfollowing the established format.