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 packagessphinx-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 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.
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