Module homepage topic type¶
The module homepage is the
index.rst file located at the root of each module documentation directory in a package.
The purpose of the module homepage is to serve as an index for all documentation related to a Python and C++ module namespace.
The module homepage links to guides and tutorials (see Generic guide topic type), task topic pages, and the Python and C++ API reference pages.
The module homepage is linked from the “Python API reference” section of the pipelines.lsst.io homepage (automatically, using the
For an example module named
lsst.example, the rendered template looks like this:
.. py:currentmodule:: lsst.example .. _lsst.example: ############ lsst.example ############ .. Paragraph that describes what this Python module does and links to related modules and frameworks. .. .. _lsst.example-using: .. Using lsst.example .. ================== .. toctree linking to topics related to using the module's APIs. .. .. toctree:: .. :maxdepth: 1 .. _lsst.example-contributing: Contributing ============ ``lsst.example`` is developed at https://github.com/lsst/example. You can find Jira issues for this module under the `example <https://jira.lsstcorp.org/issues/?jql=project%20%3D%20DM%20AND%20component%20%3D%20example>`_ component. .. If there are topics related to developing this module (rather than using it), link to this from a toctree placed here. .. .. toctree:: .. :maxdepth: 1 .. _lsst.example-command-line-taskref: Task reference ============== .. _lsst.example-pipeline-tasks: Pipeline tasks -------------- .. lsst-pipelinetasks:: :root: lsst.example .. _lsst.example-command-line-tasks: Command-line tasks ------------------ .. lsst-cmdlinetasks:: :root: lsst.example .. _lsst.example-tasks: Tasks ----- .. lsst-tasks:: :root: lsst.example :toctree: tasks .. _lsst.example-configs: Configurations -------------- .. lsst-configs:: :root: lsst.example :toctree: configs .. .. _lsst.example-scripts: .. Script reference .. ================ .. .. TODO: Add an item to this toctree for each script reference topic in the scripts subdirectory. .. .. toctree:: .. :maxdepth: 1 .. .. _lsst.example-pyapi: Python API reference ==================== .. automodapi:: lsst.example :no-main-docstr: :no-inheritance-diagram:
The next sections describe the key components of the module homepage.
File name and location¶
This file must be named
index.rst and must be located in a module documentation directory within a package.
For example, if the module’s name is
lsst.example, the full path for the file is
The top of the module homepage
index.rst file should have a py:currentmodule directive with the module’s namespace as an argument.
.. py:currentmodule:: lsst.example
This allows you to reference APIs relative to that base namespace. For example these two Python API cross-references are equivalent:
`MyClass` and `lsst.example.MyClass`.
The title (top-level header) of the module homepage is the module’s name, without any special formatting (like code literals).
In the future we might include a brief descriptive phrase after the module’s name. There is no guidance to add this descriptive phrase at this time.
The cross-reference target above the title must be the name of the module (see the example from the starter template).
Directly below the title you should add one or more (though not many) paragraphs that describe what the module is for, highlight key features that the module provides, and link to other modules that are related to this module.
The purpose of these paragraphs is not to get into fine details and usage instructions. Rather, the purpose is to help the reader navigate through the docs. With this information, the reader should be able to figure out whether this module is relevant to their task in less than a minute and either continue reading or keep searching.
Using <module> and toctrees¶
After the context paragraphs, you can add one or more sections containing just toctree directives. These toctrees link to individual topic pages, such as explanations for how the APIs work and tutorials for using the APIs. These topics follow the Generic guide topic type. We haven’t settled on specific guidelines yet for these guides and tutorials.
In most cases, you can add a single section titled “Using <module>” containing a toctree that links to the pages:
Using lsst.example ================== .. toctree:: :maxdepth: 1 howto-a howto-b
This section puts the module in context as an open source development project. The template seeds this section with links to the GitHub repository for the module’s corresponding package and a ticket search with the module’s corresponding Jira component (if the package does not have a Jira component, request one in #dm-square).
If there is documentation describing how to develop (contribute) to the module, as opposed to using the APIs, you should link to those topics with a toctree in this section.
Task reference section¶
This section lists any tasks, pipeline tasks, command-line tasks, and standalone configuration classes that are provided by the module. See the Task topic type and Config topic type pages for descriptions of how to document tasks and standalone configuration classes.
Since the content for this section is automatically generated through Sphinx extensions, refer to the template and example for the boilerplate needed to implement this section. There are two scenarios where the boilerplate needs to be customized:
- If a module does not provide pipeline tasks, command-line tasks, regular tasks, or standalone config classes, omit the corresponding subsections from the “Task reference” section. If a module does not provide any of these topic types, omit the “Task reference” section entirely.
- If the module does not provide tasks, but does provide either pipeline tasks or command-line tasks, move the
:toctree: tasksfield to either of
lsst-cmdlinetasks. One (and only one) of
lsst-tasksneeds to include the
:toctree: tasksfield — it doesn’t matter which, though.
For more information, refer to these sections in Documenteer’s documentation:
Script reference section¶
This section lists command-line scripts, aside from those that are implemented as command-line tasks, that are provided by the package and implemented by the module. These scripts can be Python scripts or any other type of shell script.
To use this section, uncomment it from the template.
Individual scripts have corresponding script topic pages in the
scripts/ subdirectory of the module documentation directory.
List each of those files in the toctree of the “Script reference” section.
For example, suppose the
scripts/ subdirectory has these contents:
scripts ├── myScript.py.rst └── myBashScript.bash.rst
The “Scripts reference” section then should look like this:
.. _lsst.example-scripts: Script reference ================ .. toctree:: :maxdepth: 1 scripts/myScript.py scripts/myBashScript.bash
Python API reference¶
The “Python API reference” section contains and links to reference information for the module’s Python APIs. These APIs are documented as Numpydoc-formatted docstrings.
The automodapi directive gathers all APIs for a given Python namespace and creates a table of contents that links to pages for each class and function. This section provides guidance on how to use automodapi to document a module, and how to work around docstring syntax errors during development.
Single automodapi directive¶
Many modules import all their public APIs into the top-level module (through
import statements in the
In this case, you only need to include one automodapi directive that points to this top-level module namespace.
.. automodapi:: lsst.example :no-main-docstr: :no-inheritance-diagram:
no-main-docstr option because the module’s docstring isn’t the primary way we document the module (that’s the purpose of the module homepage).
no-main-docstr eliminates this clutter.
no-inheritance-diagram option disables a class inheritance from being shown for the module.
If the inheritance diagram is useful, this option can be omitted.
Multiple automodapi directives¶
Some modules don’t import all public APIs into the top-level module. Instead, users are expected to import modules individually. For this case, you can add an automodapi directive for each module that a user may need to import from:
.. automodapi:: lsst.example.moduleA :no-main-docstr: :no-inheritance-diagram: .. automodapi:: lsst.example.moduleB :no-main-docstr: :no-inheritance-diagram:
Controlling what is documented¶
You may need to exclude APIs from automodapi for two reasons:
- The API is not public, so it shouldn’t be published in documentation.
- The API includes a broken docstring, and you need to remove that API temporarily.
The main tool for removing non-public APIs from the published documentation is
Each module should provide an
__all__ that explicitly lists the module’s public APIs.
Temporarily removing APIs¶
To resolve docstring syntax errors, you might need to temporarily remove one or more APIs from the documentation build. automodapi provides a few options to help with this.
skip option to remove one or more specific APIs:
.. automodapi:: lsst.example :no-main-docstr: :no-inheritance-diagram: :skip: ClassA, ClassB, functionC
Alternatively, you can allow only one or more certain APIs with the
.. automodapi:: lsst.example :no-main-docstr: :no-inheritance-diagram: :allowed-package-names: ClassA, ClassB
The module homepage topic type will continue to evolve. These are the near-term development themes:
- C++ API reference section
- Clearer organization of the “Using <module>” section.
- EUPS dependencies: an automatically-generated list of both direct and implicit EUPS package dependencies.