Package homepage topic type¶

The package homepage is the index.rst file located at the root of each package documentation directory. The purpose of the package homepage is to provide summary information about a package and a table of contents for additional topics in the package documentation directory.

Starter template¶

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

For an example package named example, the rendered template looks like this:

.. _example_dataonly-package:

.. Title is the EUPS package name

################
example_dataonly
################

.. Add a sentence/short paragraph describing what the package is for.

The ``example_dataonly`` package provides [...].

.. .. _lsst.example.dataonly-using:

.. Using example_dataonly
.. ======================

.. toctree linking to topics related to using the package's data.

.. .. toctree::
..    :maxdepth: 1

.. _example_dataonly-contributing:

Contributing
============

``lsst.example.dataonly`` is developed at https://github.com/lsst/example_dataonly.
You can find Jira issues for this module under the `example_dataonly <https://jira.lsstcorp.org/issues/?jql=project%20%3D%20DM%20AND%20component%20%3D%20example_dataonly>`_ 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

The next sections describe the key components of the package homepage.

File name and location¶

This file must be named index.rst and must be located in a package documentation directory within a package. For example, if the package’s name is example, the full path for the file is doc/example/index.rst.

Title¶

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

Note

In the future we might include a brief descriptive phrase after the package’s name. There is no guidance to add this descriptive phrase at this time.

The cross-reference target above the title must be name of the package followed by a -package suffix (see the example from the starter template).

Context paragraph¶

Directly after the title, include one or two paragraphs that describe what the module is for. The purpose of this content is not to describe the package in detail, or how to use it, but instead to quickly orient a reader.

You can also mention related packages:

Definitions of metrics and their specifications are provided separately in the :doc:`/packages/verify_metrics/index` package.

If a package provides datasets (such as a test data repository), you can summarize what these datasets are for, and what APIs use those datasets.

Contributing section¶

This section puts the package in context as an open source development project. The template <package-homepage-template> seeds this section with links to the GitHub repository for the package and a ticket search with the package’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 package, as opposed to using the package, you should link to those topics with a toctree in this section.

Modules section¶

The Modules section is designed to provide links to the module homepages for each module provided by the package. See the starter template’s example for how this section is presented.

Using <package> section¶

If the package documentation directory includes additional topics, in separate reStructuredText files, you should link to them in this section using a toctree directive. For example, given a package named example with files doc/example/topic-a.rst and doc/example/topic-b.rst, the “Using” section should be presented like this:

Using example
=============

.. toctree::
   :maxdepth: 1

   topic-a
   topic-b

Each of these other reStructuredText files should follow the Generic guide topic type.

Future components¶

The package homepage topic type will continue to evolve. These are some possible additions:

EUPS dependencies: an automatically-generated list of both direct and implicit EUPS package dependencies.
Development guides: a section linking to topics specifically about how to develop this package.