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

A custom Sphinx HTML theme is included in the astropy-helpers package (it is also included in Astropy’s source package, but this will be removed after v0.4 and subsequently only be available through astropy-helpers). This allows the theme to be used by both Astropy and affiliated packages. This is done by setting the theme in the global Astropy sphinx configuration, which is imported in the sphinx configuration of both Astropy and affiliated packages.

Using a different theme for astropy or 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.

Adding more custom themes to astropy

Additional custom themes can be included in the astropy source tree by placing them in the directory astropy/astropy/sphinx/themes, and editing astropy/astropy/sphinx/setup_package.py to include the theme (so that it is installed).

Sphinx extensions

Astropy-helpers includes a number of sphinx extensions that are used in Astropy and its affiliated packages to facilitate easily documenting code in a homogeneous and readable way.

Note

These extensions are also included with Astropy itself in v0.4 and below, to facilitate backwards-compatibility for existing affiliated packages. The versions actually in astropy will not receive further updates, however, and will likely be removed in a future version. So we strongly recommend using the astropy-helper versions instead.

automodapi Extension

This sphinx extension adds a tools to simplify generating the API documentation for Astropy packages and affiliated packages.

automodapi directive

This directive takes a single argument that must be a module or package. It will produce a block of documentation that includes the docstring for the package, an automodsumm directive directive, and an automod-diagram directive if there are any classes in the module. If only the main docstring of the module/package is desired in the documentation, use automodule instead of automodapi.

It accepts the following options:

• :no-inheritance-diagram:

  If present, the inheritance diagram will not be shown even if the module/package has classes.

• :skip: str

  This option results in the specified object being skipped, that is the object will not be included in the generated documentation. This option may appear any number of times to skip multiple objects.

• :no-main-docstr:

  If present, the docstring for the module/package will not be generated. The function and class tables will still be used, however.

• :headings: str

  Specifies the characters (in one string) used as the heading levels used for the generated section. This must have at least 2 characters (any after 2 will be ignored). This also must match the rest of the documentation on this page for sphinx to be happy. Defaults to “-^”, which matches the convention used for Python’s documentation, assuming the automodapi call is inside a top-level section (which usually uses ‘=’).

• :no-heading:

  If specified do not create a top level heading for the section. That is, do not create a title heading with text like “packagename Package”. The actual docstring for the package/module will still be shown, though, unless :no-main-docstr: is given.

• :allowed-package-names: str

  Specifies the packages that functions/classes documented here are allowed to be from, as comma-separated list of package names. If not given, only objects that are actually in a subpackage of the package currently being documented are included.

This extension also adds two sphinx configuration options:

• automodapi_toctreedirnm

  This must be a string that specifies the name of the directory the automodsumm generated documentation ends up in. This directory path should be relative to the documentation root (e.g., same place as index.rst). Defaults to 'api'.

• automodapi_writereprocessed

  Should be a bool, and if True, will cause automodapi to write files with any automodapi sections replaced with the content Sphinx processes after automodapi has run. The output files are not actually used by sphinx, so this option is only for figuring out the cause of sphinx warnings or other debugging. Defaults to False.

automodsumm Extension

This sphinx extension adds two directives for summarizing the public members of a module or package.

These directives are primarily for use with the automodapi extension, but can be used independently.

automodsumm directive

This directive will produce an “autosummary”-style table for public attributes of a specified module. See the sphinx.ext.autosummary extension for details on this process. The main difference from the autosummary directive is that autosummary requires manually inputting all attributes that appear in the table, while this captures the entries automatically.

This directive requires a single argument that must be a module or package.

It also accepts any options supported by the autosummary directive- see sphinx.ext.autosummary for details. It also accepts two additional options:

• :classes-only:

  If present, the autosummary table will only contain entries for classes. This cannot be used at the same time with :functions-only: .

• :functions-only:

  If present, the autosummary table will only contain entries for functions. This cannot be used at the same time with :classes-only: .

• :skip: obj1, [obj2, obj3, ...]

  If present, specifies that the listed objects should be skipped and not have their documentation generated, nor be included in the summary table.

• :allowed-package-names: pkgormod1, [pkgormod2, pkgormod3, ...]

  Specifies the packages that functions/classes documented here are allowed to be from, as comma-separated list of package names. If not given, only objects that are actually in a subpackage of the package currently being documented are included.

This extension also adds one sphinx configuration option:

• automodsumm_writereprocessed

  Should be a bool, and if True, will cause automodsumm to write files with any automodsumm sections replaced with the content Sphinx processes after automodsumm has run. The output files are not actually used by sphinx, so this option is only for figuring out the cause of sphinx warnings or other debugging. Defaults to False.

automod-diagram directive

This directive will produce an inheritance diagram like that of the sphinx.ext.inheritance_diagram extension.

This directive requires a single argument that must be a module or package. It accepts no options.

Note

Like ‘inheritance-diagram’, ‘automod-diagram’ requires graphviz to generate the inheritance diagram.

edit_on_github Extension

This extension makes it easy to edit documentation on github.

It adds links associated with each docstring that go to the corresponding view source page on Github. From there, the user can push the “Edit” button, edit the docstring, and submit a pull request.

It has the following configuration options (to be set in the project’s conf.py):

• edit_on_github_project

  The name of the github project, in the form “username/projectname”.

• edit_on_github_branch

  The name of the branch to edit. If this is a released version, this should be a git tag referring to that version. For a dev version, it often makes sense for it to be “master”. It may also be a git hash.

• edit_on_github_source_root

  The location within the source tree of the root of the Python package. Defaults to “lib”.

• edit_on_github_doc_root

  The location within the source tree of the root of the documentation source. Defaults to “doc”, but it may make sense to set it to “doc/source” if the project uses a separate source directory.

• edit_on_github_docstring_message

  The phrase displayed in the links to edit a docstring. Defaults to “[edit on github]”.

• edit_on_github_page_message

  The phrase displayed in the links to edit a RST page. Defaults to “[edit this page on github]”.

• edit_on_github_help_message

  The phrase displayed as a tooltip on the edit links. Defaults to “Push the Edit button on the next page”

• edit_on_github_skip_regex

  When the path to the .rst file matches this regular expression, no “edit this page on github” link will be added. Defaults to "_.*".

numpydoc Extension

This extension (and some related extensions) are a port of the numpydoc extension written by the NumPy and SciPy, projects, with some tweaks for Astropy. Its main purposes is to reprocess docstrings from code into a form sphinx understands. Generally, there’s no need to interact with it directly, as docstrings following the Astropy Docstring Rules will be processed automatically.

Other Extensions

astropy_helpers.sphinx.ext includes a few other extensions that are primarily helpers for the other extensions or workarounds for undesired behavior. Their APIs are not included here because we may change them in the future.