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 package-toctree directive).

Starter template

The stack_package project template includes the Jinja-formatted template for the module homepage.

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 doc/lsst.example/index.rst.

Preamble

The top of the module homepage index.rst file should have a py:currentmodule directive with the module’s namespace as an argument. For example:

.. 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`.

Title

The title (top-level header) of the module homepage is the module’s name, without any special formatting (like code literals).

Note

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).

Context paragraph

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

Design and development section

This section collects documentation related to the design and development of the module. As opposed to pages in the Using section, such content is for an “internal” developer and maintainer audience. We keep this content in the public documentation, though, because LSST software is open source and has a sophisticated user base that could benefit from transparent developer documentation. Maintaining design and development documentation documentation here also ensures that the content lives and evolves with the code.

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).

Below the preamble, you can link to additional pages related to the module’s design and development with a toctree. All design and development pages should be contained in a subdirectory called dev:

.. toctree::
   :maxdepth: 1

   dev/design-overview
   dev/development-guidelines

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:

1. 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.
2. If the module does not provide tasks, but does provide either pipeline tasks or command-line tasks, move the :toctree: tasks field to either of lsst-pipelinetasks or lsst-cmdlinetasks. One (and only one) of lsst-pipelinetasks, lsst-cmdlinetasks, or lsst-tasks needs to include the :toctree: tasks field — it doesn’t matter which, though.

For more information, refer to these sections in Documenteer’s documentation:

• lsst-tasks
• lsst-cmdlinetasks
• lsst-pipelinetasks
• lsst-configs

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 __init__.py file). In this case, you only need to include one automodapi directive that points to this top-level module namespace. For example:

.. automodapi:: lsst.example
   :no-main-docstr:
   :no-inheritance-diagram:

Note

We use 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). Thus using no-main-docstr eliminates this clutter.

The 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:

1. The API is not public, so it shouldn’t be published in documentation.
2. 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 __all__. Each module should provide an __all__ that explicitly lists the module’s public APIs. automodapi respects __all__.

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.

Use the 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 allowed-package-names option:

.. automodapi:: lsst.example
   :no-main-docstr:
   :no-inheritance-diagram:
   :allowed-package-names: ClassA, ClassB

Tip

Remember to “clean” the documentation build when changing what docstrings are included using the stack-docs clean or package-docs clean commands. Otherwise, the cached documentation stub page will remain in the build.

Future components

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.