Metadata-Version: 2.4
Name: sphinx-astropy
Version: 1.11
Summary: Sphinx extensions and configuration specific to the Astropy project
Author-email: The Astropy Developers <astropy.team@gmail.com>
License-Expression: BSD-3-Clause
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python
Classifier: Programming Language :: Python :: 3
Classifier: Operating System :: OS Independent
Requires-Python: >=3.10
Description-Content-Type: text/x-rst
License-File: LICENSE.rst
Requires-Dist: astropy-sphinx-theme
Requires-Dist: numpydoc
Requires-Dist: packaging
Requires-Dist: pillow
Requires-Dist: pytest-doctestplus>=0.11
Requires-Dist: sphinx-automodapi
Requires-Dist: sphinx-gallery
Requires-Dist: sphinx>=4.0.0
Requires-Dist: sphinxcontrib-jquery
Provides-Extra: confv2
Requires-Dist: pydata-sphinx-theme; extra == "confv2"
Requires-Dist: sphinx-copybutton; extra == "confv2"
Provides-Extra: confv3
Requires-Dist: sphinx-astropy[confv2]; extra == "confv3"
Requires-Dist: astropy-sphinx-theme>=3.0.0; extra == "confv3"
Provides-Extra: all
Requires-Dist: astropy; extra == "all"
Provides-Extra: tests
Requires-Dist: pytest; extra == "tests"
Dynamic: license-file

About
=====

.. image:: https://zenodo.org/badge/119399685.svg
   :target: https://zenodo.org/badge/latestdoi/119399685
   :alt: Zenodo DOI

.. image:: https://github.com/astropy/sphinx-astropy/actions/workflows/python-tests.yml/badge.svg
   :target: https://github.com/astropy/sphinx-astropy/actions/workflows/python-tests.yml
   :alt: CI Status

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:

.. code-block:: python

    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:

.. code-block:: python

    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 <http://www.sphinx-doc.org>`_

* `astropy-sphinx-theme <https://github.com/astropy/astropy-sphinx-theme>`_ - the default 'bootstrap' theme use by Astropy and a number of affiliated packages. This goes with ``sphinx_astropy.conf.v1``.

* `sphinx-automodapi <http://sphinx-automodapi.readthedocs.io>`_ - an extension that makes it easy to automatically generate API documentation.

* `sphinx-gallery <https://sphinx-gallery.readthedocs.io/en/latest/>`_ - an extension to generate example galleries

* `numpydoc <https://numpydoc.readthedocs.io>`_ - an extension to parse docstrings in NumpyDoc format

* `pillow <https://pillow.readthedocs.io/en/latest/>`_ - a package to deal with
  images, used by some examples in the astropy core documentation.

* `pytest-doctestplus <https://github.com/astropy/pytest-doctestplus/>`_ - providing the 'doctestplus' extension to skip code snippets in narrative documentation.

pydata-sphinx-theme (confv2)
^^^^^^^^^^^^^^^^^^^^^^^^^^^^

To use the new ``pydata-sphinx-theme`` with ``sphinx_astropy.conf.v2``, you have to install
the optional ``[confv2]`` dependencies::

    pip install sphinx-astropy[confv2]

That would pull in the following as well:

* `pydata-sphinx-theme <https://github.com/pydata/pydata-sphinx-theme/>`_ - a clean, three-column,
  Bootstrap-based Sphinx theme by and for the `PyData community <https://pydata.org/>`_.

* `sphinx-copybutton <https://github.com/executablebooks/sphinx-copybutton>`_ - a small Sphinx
  extension to add a "copy" button to code blocks.

``astropy-unified`` theme (confv3)
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

To use the new ``astropy-unified`` theme, which is a derivative of ``pydata-sphinx-theme`` and ``sunpy-sphinx-theme`` with ``sphinx_astropy.conf.v3``, you have to install
the optional ``[confv3]`` dependencies::

    pip install sphinx-astropy[confv3]

This would pull in the following as well:

* ``astropy-sphinx-theme >=3.0``
* All ``confv3`` dependencies.
