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.

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

Contributing section

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.

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

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

.. automodapi:: lsst.example.moduleB

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
   :skip: ClassA, ClassB, functionC

Alternatively, you can allow only one or more certain APIs with the allowed-package-names option:

.. automodapi:: lsst.example
   :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
  • Task reference section
  • Clearer organization of the “Using <module>” section.