Documentation Guidelines#

High-quality, consistent documentation for astronomy code is one of the major goals of the Astropy Project. We encourage you to help us improve the documentation, and you do not have to be an expert on astropy to do so! If something in the docs does not make sense to you, updating the relevant section after you figure it out is a great way to contribute to Astropy and help others in the future.

In this section we describe our documentation procedures and rules that apply to the astropy core package and coordinated packages. We encourage affiliated packages to do the same.

Astropy Documentation Overview#

The documentation is written in reStructuredText, which is almost like writing in plain English, and built using Sphinx. The Sphinx Documentation has an excellent introduction to reST that you should read.

The Astropy documentation consists of two parts. The code docstrings provide a clear explanation of the usage of individual functions, classes and modules. These are collected by Sphinx into the API documentation. The narrative documentation is contained in the source code docs directory and provides a more tutorial-like overview of each sub-package together with other topical information like What’s New, Installation, Developer documentation, etc.

The OpenAstronomy Packaging Guide provides a recommended general structure for documentation.

Astropy Documentation 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.

  • Documentation text should follow the Astropy Narrative Style Guide.

  • Docstrings must be provided for all public classes, methods, and functions, and be written using the numpydoc format.

  • References in docstrings, including internal Astropy links, should use the intersphinx format. For example a link to the Astropy section on unit equivalencies would be `` Equivalencies . When built in Astropy, links starting with 'astropy' resolve to the current build. In affiliated packages using the ``sphinx-astropy intersphinx mapping, the links resolve to the stable version of Astropy. For linking to the development version, use direct URL linking.

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

  • Optional package dependencies should be documented where feasible.

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

Building the Documentation from Source#

There are two ways to build the Astropy documentation. The first way is to execute the following tox command from within the astropy source directory:

tox -e build_docs

With this method you do not need to install any of the documentation dependencies. The documentation will be built in the docs/_build/html directory, and can be read by pointing a web browser to docs/_build/html/index.html.

The second method is to build the documentation manually. This requires that you are working in an isolated development environment as described in Creating a development environment. The benefit of this method is that often you can rebuild the docs fairly quickly after making changes.

cd docs
make html

The documentation will be generated in the same location. In some cases if you make changes they will not be reflected in the build output and you need to start over after running make clean.

To use multiple cores for building faster, run:

SPHINXOPTS="-j auto" make html

Dependencies#

Here we describe the key dependencies for building the documentation. These are provided by the docs optional dependencies in the astropy package (see the [docs] list in [project.optional-dependencies] in pyproject.toml).

The sphinx-astropy package provides configuration common to packages in the Astropy ecosystem and serves as a way to automatically get the other main dependencies, including:

  • Sphinx - the main package we use to build the documentation

  • astropy-sphinx-theme - the default ‘bootstrap’ theme used by astropy and a number of affiliated packages

  • sphinx-automodapi - an extension that makes it easy to automatically generate API documentation

  • numpydoc - an extension to parse docstrings in NumPyDoc format

  • Graphviz - generate inheritance graphs (available as a conda package or a system install but not in pip)

Note

Both of the pip install methods above do not include Graphviz. If you do not install this package separately then the documentation build process will produce a very large number of lengthy warnings (which can obscure bona fide warnings) and also not generate inheritance graphs.

Reporting Issues/Requesting Features#

As mentioned above, building the documentation depends on a number of Sphinx extensions and other packages. Since it is not always possible to know which package is causing issues or would need to have a new feature implemented, you can open an issue in the core astropy package issue tracker. However, if you wish, you can also open issues in the repositories for some of the dependencies:

  • For requests/issues related to the appearance of the docs (e.g. related to the CSS), you can open an issue in the astropy-sphinx-theme issue tracker.

  • For requests/issues related to the auto-generated API docs which appear to be general issues rather than an issue with a specific docstring, you can use the sphinx-automodapi issue tracker.

  • For issues related to the default configuration (e.g which extensions are enabled by default), you can use the sphinx-astropy issue tracker.

Details for Package Maintainers#

Following is useful information for package maintainers who are using the Astropy documentation infrastructure and may want to customize it for their package.

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.

  • 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