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 we try to keep to these as closely as possible, while the standards for affiliated packages are somewhat looser. (These procedures and guidelines are still recommended for affiliated packages, as they encourage useful documentation, a characteristic often lacking in professional astronomy software.)

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 format affiliated packages that must follow for consideration of integration into the core module, 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 template package will provide a recommended general structure for documentation.

• Docstrings must be provided for all public classes, methods, and functions.

• Docstrings will be incorporated into the documentation using a version of numpydoc included with Astropy, and should follow the Astropy Docstring Rules.

• Examples and/or tutorials are strongly encouraged for typical use-cases of a particular module or class.

• Any external package dependencies aside from NumPy, SciPy, or Matplotlib must be explicitly mentioned in the documentation. They should also be recorded in the setup.py file in the root of the astropy repository, optionally using an extras_require entry.

• Configuration options using the astropy.config mechanisms must be explicitly mentioned in the documentation.

The details of the docstring format are described on a separate page:

• Astropy Docstring Rules
  • Overview
  • Docstring Standard
  • Sections
  • Documenting classes
    • Class docstrings
    • Method docstrings
  • Documenting class instances
  • Documenting constants
  • Documenting modules
  • Other points to keep in mind
  • Common reST concepts
  • Conclusion

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 in package-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 the html_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

Note that packages that make use of astropy-helpers have access to the:

python setup.py build_docs

command. Provided that Sphinx is installed, the above command will temporarily install sphinx-astropy and all its dependencies automatically.