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.
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
The title (top-level header) of the package homepage is the packages’s name, without any special formatting (like code literals).
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).
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-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.
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.