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 homepage 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.
COPYRIGHT¶
We assert copyright information in a centralized COPYRIGHT
file, located in the repository’s root, instead of in individual source files.
Using a COPYRIGHT
file allows us to maintain copyright information more effectively than in source code comments.
(See RFC-45 and this article from the Software Freedom Law Center for background on this policy).
During LSST construction, copyright is asserted by your employer and not centrally by AURA.
The COPYRIGHT
file should include a line for each legal entity that contributed to the package.
A common example may look like:
Copyright 2012-2015 LSST Corporation
Copyright 2015-2017 Association of Universities for Research in Astronomy
Where the year range is changed as appropriate. If the code in a package has not been touched since 2015 and you are working on it in 2018, do not say “2012-2018” but instead use “2012-2015, 2018”. You can determine this by looking at the repository change history.
Note
Previously it was common to see AURA/LSST in the copyright assignment line. This is not a legal entity and the fully-expanded name of AURA should be used.
Use a line per institution even if the years are the same: E.g.:
Copyright 2012-2015 LSST Corporation
Copyright 2012-2015 University of Washington
Copyright 2015-2018 Association of Universities for Research in Astronomy
These COPYRIGHT
files should be updated during development and may be robotically refreshed.
Automatically updating the files requires people committing to the repository use their institutional email address.
If you move source files between packages, remember to audit the COPYRIGHT
file and move copyright assignments between packages as necessary.
Note
Some code written before construction officially started will have an LSST Corporation copyright and this should not be changed unless it has erroneously been used for code after construction began in August 2015.
Standard Institutional Copyrights¶
The institutions contributing to the Data Management software use the following copyright statements:
- Association of Universities for Research in Astronomy
- University of Washington
- The Trustees of Princeton University
- The Board of Trustees of the Leland Stanford Junior University, through SLAC National Accelerator Laboratory
- University of Illinois Champaign-Urbana
- California Institute of Technology
Contributions from institutions or individuals outside of DM are accepted and the relevant copyright statement should be included in the file if appropriate. We do not require copyright assignment to AURA on external code contributions, but be aware that small patches are not generally sufficient to require assertion of copyright by the contributor.
LICENSE¶
A LICENSE
file in the repository’s root is the canonical description of LSST’s code licensing.
We use the GPLv3 license and a copy of it can be obtained from https://www.gnu.org/licenses/gpl.txt.
CODE PREAMBLE¶
Each source file needs to include a short license and copyright statement. This should normally be included in a comment block at the top of the file and should take the following form:
This file is part of %package_name%.
Developed for the LSST Data Management System.
This product includes software developed by the LSST Project
(http://www.lsst.org).
See the COPYRIGHT file at the top-level directory of this distribution
for details of code ownership.
This program is free software: you can redistribute it and/or modify
it under the terms of the GNU General Public License as published by
the Free Software Foundation, either version 3 of the License, or
(at your option) any later version.
This program is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
GNU General Public License for more details.
You should have received a copy of the GNU General Public License
along with this program. If not, see <http://www.gnu.org/licenses/>.
where the package name is stated explicitly at the top to attach it to a particular COPYRIGHT
file.
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.