/sphinx-astropy

Sphinx functionality for Astropy

Primary LanguagePythonBSD 3-Clause "New" or "Revised" LicenseBSD-3-Clause

About

This package serves two purposes: it provides a default Sphinx configuration and set of extensions specific to the Astropy project, and it acts as a meta-package by installing all required Sphinx extensions for the core Astropy package and other packages.

Sphinx configuration

The default Sphinx configuration can be imported by putting:

from sphinx_astropy.conf import *

at the top of your conf.py file. You can then override specific settings from this default configuration, such as adding extensions or intersphinx packages. To give a clearer error messages for users, you can instead write:

try:
    from sphinx_astropy.conf import *
except ImportError:
    print('ERROR: the documentation requires the sphinx-astropy package to be installed')
    sys.exit(1)

Dependencies/extensions

Installing sphinx-astropy will automatically install (if not already present):

  • Sphinx
  • astropy-sphinx-theme - the default 'bootstrap' theme use by Astropy and a number of affilited packages.
  • 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
  • pillow - a package to deal with images, used by some examples in the astropy core documentation.
  • pytest-doctestplus - providing the 'doctestplus' extension to skip code snippets in narrative documentation.