DM-14782: Replace astropy_helpers with sphinx-automodapi and improve Sphinx configurations for stack documentation #36
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
This attribute is expected by sphinx.cmd.build.handle_exception.
Use the patch_docutils context added with Sphinx 1.7.
Refactoring build_package_configs should make it easier to reuse configurations for the primary Sphinx build in pipelines_lsst_io.
Turns out that h5py is not used in the stack, so there's no need to add it to intersphinx.
Instead of obtaining numpydoc and automodapi through astropy_helpers, this allows us to get that code directly through their standalone packages. This is made possible by Astropy's recent moves to break up astropy_helpers into smaller sub-dependencies.
This will make the doc build smaller since we're not rendering the entire source code base. Ideally we want to link to the source code on GitHub, but this will need extra work to resolve which Git repo a given API comes from.
jonathansick
changed the title
jonathansick
force-pushed
the
tickets/DM-14782
branch
from
7d5ca30 to
541f756
Compare
The autodoc_default_flags configuration allows us to set default flags for all autodoc directives that are created by automodapi. special-members is the important flag. Set autoclass_content = class. This enforces the LSST DM policy of not writing in the __init__ docstring. Disable the `inherited-members` flag. This didn't work will with the lsst.verify documentation. The code comments and DM-14782 ticket have additional descritpions.
python, numpy, scipy, and matplotlib switched to https from http protocols.
This function works like build_package_configs but is specifically intended to configure the pipelines_lsst_io main documentation package. This pattern lets us share configurations between pipelines_lsst_io "stack" builds and the per-package builds.
jonathansick
force-pushed
the
tickets/DM-14782
branch
from
541f756 to
efba06f
Compare
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.
Various improvements to the configuration for LSST Stack-based documentation projects (
documenteer.sphinxconf.stackconf):Replaced the third-party
astropy_helperspackage with the numpydoc andsphinx-automodapipackages. This helps reduce the number of extraneous dependencies needed for Stack documentation.Special methods (dunder methods) are now included in API documentation (
autodoc_default_flagsincludesspecial-members).autoclass_contentis now"class", fitting the LSST DM standards for writing class docstrings, and not filling out__init__docstrings.Removed h5py from intersphinx since it was never needed.
Removed the viewcode extension since that won't scale well with the LSST codebase. Ultimately we want to link to source on GitHub.
Other internal cleanups for
documenteer.sphinxconf.stackconf.Fixes #26 and #27