Documenting Stack Packages¶
Note
This is a preview documentation format specification. Software documentation should currently be written in the format described at https://confluence.lsstcorp.org/display/LDMDG/Documentation+Standards
The LSST Stack is an aggregation of packages contained in individual git repositories (see github.com/lsst). This page explains how to organize and write package documentation that can be integrated into software documentation, such as the LSST Science Pipelines docs. In separate pages we cover writing docstrings for Python and C++, respectively. We use reStructuredText to markup our documentation; see our reStructuredText Style Guide for more information on this markup language.
Layout of a Package: The Doc Perspective¶
From a perspective of documentation, the repository of every Stack package is laid out as follows:
package_name/
\ _ ... source files
|_ README.rst
|_ LICENSE
|_ COPYRIGHT
|_ CONTRIBUTING.rst
|_ docs/
\_ index.rst
In the follow sections we describe how to produce the content for each of these documentation files and directories.
Developer Documentation: GitHub Summary, README, LICENSE, COPYRIGHT & CONTRIBUTING¶
Each repository needs a few files and pieces of metadata to make them approachable for developers.
GitHub Summary Line¶
From the root GitHub page of a Stack repository (e.g., https://github.com/lsst/afw), you can add/edit the repository’s summary and homepage link, located directly below the repository’s name.
The summary should be a concise one-sentence description the repository. These summaries are critical for browsing repositories at https://github.com/lsst and for GitHub search.
The hompage should be set to the package’s user guide page in the deployed software documentation (point to the ‘latest’ branch of the documentation).
README.rst¶
Every repository needs a README.
READMEs are especially important since GitHub features them prominently on repository homepages. At the same time, READMEs aren’t a primary source of Stack documentation. Thus we recommend you use your README to describe the purpose of the repository in slightly more detail than the GitHub summary line, and to point developers to the Stack documentation. At your discretion, READMEs can also be used for developer-centric notices that you feel shouldn’t be included in the main documentation.
To be consistent with the rest of the Stack’s documentation, READMEs should be in reStructuredText format and named README.rst
in the root of your repository.
We suggest this template:
============
package_name
============
{{repeat GitHub summary line}}
``package_name`` is a package in the LSST Stack.
Documentation: {{doc url}}
{{Additional descriptions and developer notices, as needed}}
License
-------
See LICENSE and COPYRIGHT files.
LICENSE¶
A LICENSE
file in the repository’s root is the canonical description of LSST’s code licensing.
The canonical source of this file’s content is https://www.lsstcorp.org/LegalNotices/LsstLicenseStatement.txt, though ensure that it is named LICENSE
in the repository.
COPYRIGHT¶
We assert copyright information in a centralized COPYRIGHT
file, located in the repository’s root.
Using a COPYRIGHT
file allows us to maintain copyright information more effectively than in source code comments.
(See RFC-45 for background on this policy).
Default Copyright¶
By default, the COPYRIGHT
file should look like:
Copyright AURA/LSST (2012-2015)
Where the year range is changed as appropriate.
Complex Copyright Assignments¶
If multiple institutions contributed to the code over the same period, each institution can be listed. E.g.:
Copyright University of Washington and AURA/LSST (2012-2015)
If multiple institutions contributed to the code, but at different times, then each institution can be listed on a separate copyright line:
Copyright AURA/LSST (2012-2015)
Copyright University of Washington (2010-2014)
As per RFC-45, these COPYRIGHT
files will be robotically refreshed.
CONTRIBUTING.rst¶
GitHub popularized the use of CONTRIBUTING files to help open source developers stay on the same page. Whenever a GitHub Issue or Pull Request is made, GitHub will display a link to the CONTRIBUTING.rst file.
#################
How to Contribute
#################
If you've found a bug or have a question
========================================
If you've found a bug, or have a question about using the LSST stack,
please join us at https://community.lsst.org and post a new topic in
the `Q&A` category <https://community.lsst.org/c/qa>`_.
At LSST we don't use GitHub issues to track work. Posting in the forum is
the best way to contact LSST developers and get help.
If you haven't consulted with it yet, the `LSST Stack Handbook
<http://lsst_stack_docs.rtd.org>`_ may also help.
If you'd like to contribute code
================================
We appreciate getting open source contributions to the LSST Stack. Thanks!
We've put together a guide for developing on the LSST Stack at
http://lsst_stack_docs.rtd.org/development/workflow.
Resources
=========
- LSST Community forum: https://community.lsst.org
- LSST Data Management Homepage: https://dm.lsst.org
- LSST Stack Handbook: https://lsst_stack_docs.rtd.org
Team Culture and Conduct Standards
==================================
All interaction within the LSST DM team, and between the community and
DM are goverened by the `LSST DM Team Culture and Conduct Standards`_.
.. _LSST DM Team Culture and Conduct Standards: https://confluence.lsstcorp.org/display/LDMDG/Team+Culture+and+Conduct+Standards
Note
Some of the documentation URLs listed in this CONTRIBUTING.rst
guide don’t exist yet.
The Package’s User Guide in docs/¶
The heart of a Stack package’s documentation are files in the docs/
directory [1].
This content is ingested by Sphinx, our documentation build tool, to publish user guides for each package.
In the following section we describe how to write the main documentation file, docs/index.rst
.
[1] | LSST’s previous Doxygen-based documentation platform placed its content in the doc/ directory.
Thus the Sphinx and Doxygen documentation can coexist during the documentation transition. |
Template for a Package’s index.rst¶
Consistent documentation patterns make it easier for users to read the Docs. For every package’s user guide, we strongly recommend using the following sections:
- “Introduction”
- “Getting Started”
- “Tutorials” (optional)
- “Using package_name”
- Discretionary sections
- “Python Reference”
- “C++ Reference”
To implement this pattern, every package’s index.rst
should follow this basic template:
.. _lsst-package-name:
###################
package_name - Slug
###################
.. _lsst-package-name-intro:
Introduction
============
Tell people what the package does (in a few paragraphs).
List features here.
.. _lsst-package-getting-started:
Getting Started
===============
A quick tutorial that covers the main functionality.
It should be *brief* (a laptop screen or two) and *shouldn't be exhaustive*.
.. _lsst-package-getting-started:
Using package_name
==================
A series of sections that cover API usage.
Subsections
-----------
Use sectioning liberally.
Other sections
==============
This is where you can put other types of content, such as more
detailed architectural descriptons for developers.
.. _lsst-package-name-py-ref:
Python Reference
================
API reference for Python developers.
.. _lsst-package-name-cpp-ref:
C++ Reference
=============
API reference for C++ developers
We recommend that the entirety of a package’s documentation be contained in a single index.rst
file.
This minimal pagination makes it easier for readers for use their browser’s search to find specific phrases.
In the following sections we expand on key concepts in writing a package’s user guide.
Sections¶
In keeping with Python community conventions and our style guide, we use the following section markup for different levels of headings:
- Page title:
#
with overline, - Sections:
=
, - Subsections:
-
, - Subsubsections:
^
, - Paragraphs:
"
.
Section Labels¶
Although Sphinx can automatically provide section link targets, we recommend that you provide explicit link targets since they don’t change when headline text changes.
Section labels should be placed directly above the header and follow the syntax _label:
.
Note that hyphens should be used to separate words in a label; underscores are only used to prefix the label.
For package documentation, we recommend that you prefix section labels with the Python namespace, joined by hyphens (-). For example, the section label for the lsst.afw
package should be:
.. _lsst-afw:
By convention, we use the following labels for standardized package sections
- “Introduction:”
lsst-package-name-intro
- “Getting Started:”
lsst-package-name-getting-started
- “Using package_name:”
lsst-package-name-using
- “Python Reference:”
lsst-package-name-py-ref
- “C++ Reference:”
lsst-package-name-cpp-ref
Titling the Package’s User Guide¶
We recommend the title for a package’s user guide follow the format
########################
lsst.package_name - Slug
########################
That is, the title should provide the Python namespace of the package first, followed by the ‘slug.’. The slug is merely a short phrase that elucidates the package’s role. For example,
################################
lsst.afw - Application Framework
################################
The ‘Introduction’ Section¶
The Introduction section should be an approachable summary of what the package does. Write the Introduction for users who have never used the package before, and need to decide quickly whether this is the package that can solve their problems or not. Including a bulleted feature list could be a good thing too, but don’t be long-winded.
The ‘Getting Started’ Section¶
The Getting Started section is a quick demo, with code that a user could paste into a Jupyter notebook and see something happen. This section isn’t meant to be a complete survey of the package’s functionality; it’s only meant to say hey there! you can actually use this thing.
The ‘Tutorials’ Section¶
This section can provide links to tutorials that use this package.
The ‘Using package_name’ Section¶
This section is the heart of the Package’s user guide. This section should be comprehensive and explain all the major functionality of the package. Code examples should be used liberally. We encourage you to divide the Using section into multiple, short, subsections to ensure it is skimable/navigable.
The ‘Python Reference’ Section¶
The Python Reference is generated automatically from the Python docstrings.
Todo
Explain how to setup autodoc directives
The ‘C++ Reference’ Section¶
The C++ Reference is generated automatically from the doxygen-formatted C++ code comments.
Todo
Explain how to setup the documentation directives
Acknowledgements¶
We credit the Astropy project for developing the Introduction - Getting Started - Using - API Reference pattern for package documentation.