Writing Documentation¶
High-quality, consistent documentation for astronomy code is one of the major goals of the Astropy Project. Hence, we describe our documentation procedures and rules here. For the astropy core project and coordinated packages we try to keep to these as closely as possible, and we encourage affiliated packages to also adhere to these as they encourage useful documentation, a characteristic often lacking in professional astronomy software.
Adding a Git Commit¶
When your changes only affect documentation (i.e., docstring or RST files)
and do not include any code snippets that require doctest to run, you may
add a [skip travis]
in your commit message. For example:
git commit -m "Update documentation about this and that [skip travis]"
When this commit is pushed out to your branch associated with a pull request, Travis CI will be skipped because it is not required. This is because the CI job to build the documentation resides in CircleCI.
Building the Documentation from source¶
For information about building the documentation from source, see the Building Documentation section in the installation instructions.
Astropy Documentation Rules and Guidelines¶
This section describes the standards for documentation that any contribution being considered for integration into the core package should follow, as well as the standard Astropy docstring format.
All documentation text should follow the Astropy Narrative Style Guide: A Writing Resource for Contributors.
All documentation should be written use the Sphinx documentation tool.
The package template provides a recommended general structure for documentation.
Docstrings must be provided for all public classes, methods, and functions.
Docstrings should follow the numpydoc format.
Examples and/or tutorials are strongly encouraged for typical use-cases of a particular module or class.
Any external package dependencies must be explicitly mentioned in the documentation. They should also be recorded in the
setup.cfg
file in the root of the astropy repository using anextras_require
entry.Configuration options using the
astropy.config
mechanisms must be explicitly mentioned in the documentation.
Sphinx Documentation Themes¶
An Astropy Project Sphinx HTML theme is included in the astropy-sphinx-theme package. This allows the theme to be used by both Astropy and affiliated packages. The theme is activated by setting the theme in the global Astropy sphinx configuration in sphinx-astropy, which is imported in the sphinx configuration of both Astropy and affiliated packages.
A different theme can be used by overriding a few sphinx configuration variables set in the global configuration.
To use a different theme, set
html_theme
to the name of a desired builtin Sphinx theme or a custom theme inpackage-name/docs/conf.py
(where'package-name'
is “astropy” or the name of the affiliated package).To use a custom theme, additionally: place the theme in
package-name/docs/_themes
and add'_themes'
to thehtml_theme_path
variable. See the Sphinx documentation for more details on theming.
Sphinx extensions¶
The documentation build process for Astropy uses a number of sphinx extensions which are all installed automatically when installing sphinx-astropy. These facilitate easily documenting code in a homogeneous and readable way.
The main extensions used are:
sphinx-automodapi - an extension that makes it easy to automatically generate API documentation.
sphinx-gallery - an extension to generate example galleries
numpydoc - an extension to parse docstrings in NumpyDoc format
In addition, the sphinx-astropy includes a few small extensions:
sphinx_astropy.ext.edit_on_github
- an extension to add ‘Edit on GitHub’ links to documentation pages.sphinx_astropy.ext.changelog_links
- an extension to add links to pull requests when rendering the changelog.sphinx_astropy.ext.doctest
- an extension that makes it possible to add metadata about doctests inside.rst
files