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.

The package homepage topic type is only used in packages that have a package documentation directory. Specifically, if a package provides a Python module, it won’t have a package documentation directory, and thus won’t have this file.

Starter template

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

For an example package named example_dataonly, 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
============

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

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.

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.