https://github.com/astropy/sphinx-astropy

Sphinx functionality for Astropy
https://github.com/astropy/sphinx-astropy

Last synced: about 1 year ago
JSON representation

Sphinx functionality for Astropy

• Host: GitHub
• URL: https://github.com/astropy/sphinx-astropy
• Owner: astropy
• License: bsd-3-clause
• Created: 2018-01-29T15:17:45.000Z (over 8 years ago)
• Default Branch: main
• Last Pushed: 2024-10-10T20:45:58.000Z (over 1 year ago)
• Last Synced: 2024-10-29T16:04:36.082Z (over 1 year ago)
• Language: Python
• Homepage:
• Size: 226 KB
• Stars: 5
• Watchers: 10
• Forks: 17
• Open Issues: 12
• Metadata Files:
  • Readme: README.rst
  • Changelog: CHANGES.rst
  • License: LICENSE.rst

Awesome Lists containing this project

README

          
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 `_

* `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 `_ - 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.

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 `_ - a clean, three-column,

  Bootstrap-based Sphinx theme by and for the `PyData community `_.

* `sphinx-copybutton `_ - a small Sphinx

  extension to add a "copy" button to code blocks.