Extensions
==========

.. seealso::
    `Sphinx Extensions
    <https://www.sphinx-doc.org/en/master/usage/extensions/index.html>`_

Built-in extensions
-------------------

`sphinx.ext.autodoc <https://www.sphinx-doc.org/en/master/usage/extensions/autodoc.html>`_
    embeds documentation from docstrings.
`sphinx.ext.autosummary <https://www.sphinx-doc.org/en/master/usage/extensions/autosummary.html>`_
    generates summaries of functions, methods, and attributes from docstrings.
`sphinx.ext.autosectionlabel <https://www.sphinx-doc.org/en/master/usage/extensions/autosectionlabel.html>`_
    references sections using the title.
`sphinx.ext.graphviz <https://www.sphinx-doc.org/en/master/usage/extensions/graphviz.html>`_
    renders `Graphviz <https://www.graphviz.org/>`_ graphs.
`sphinx.ext.ifconfig <https://www.sphinx-doc.org/en/master/usage/extensions/ifconfig.html>`_
    includes content only under certain conditions.
`sphinx.ext.intersphinx <https://www.sphinx-doc.org/en/master/usage/extensions/intersphinx.html>`_
    allows the inclusion of other project documentation.
`sphinx.ext.mathjax <https://www.sphinx-doc.org/en/master/usage/extensions/math.html#module-sphinx.ext.mathjax>`_
    renders mathematical formulas using JavaScript.
`sphinx.ext.napoleon <https://www.sphinx-doc.org/en/master/usage/extensions/napoleon.html>`_
    supports NumPy and Google Style docstrings.

`sphinx.ext.todo <https://www.sphinx-doc.org/en/master/usage/extensions/todo.html>`_
    supports to-do items.
`sphinx.ext.viewcode <https://www.sphinx-doc.org/en/master/usage/extensions/viewcode.html>`_
    adds links to the source code of the Sphinx documentation.

.. seealso::
    `sphinx/sphinx/ext/
    <https://github.com/sphinx-doc/sphinx/tree/master/sphinx/ext>`_

Third-party extensions
----------------------

`Breathe <https://github.com/breathe-doc/breathe>`_
    ReStructuredText and Sphinx bridge to `Doxygen <https://www.doxygen.nl>`_.

    .. image:: https://raster.shields.io/github/stars/breathe-doc/breathe
       :alt: Stars
       :target: https://github.com/breathe-doc/breathe

    .. image:: https://raster.shields.io/github/contributors/breathe-doc/breathe
       :alt: Contributors
       :target: https://github.com/breathe-doc/breathe/graphs/contributors

    .. image:: https://raster.shields.io/github/commit-activity/y/breathe-doc/breathe
       :alt: Commit activity
       :target: https://github.com/breathe-doc/breathe/graphs/commit-activity

    .. image:: https://raster.shields.io/github/license/breathe-doc/breathe
       :alt: Lizenz

`sphinx-autobuild <https://github.com/sphinx-doc/sphinx-autobuild>`_
    monitors a Sphinx repository and generates new documentation as soon as
    changes are made.

    .. image:: https://raster.shields.io/github/stars/sphinx-doc/sphinx-autobuild
       :alt: Stars
       :target: https://github.com/sphinx-doc/sphinx-autobuild

    .. image:: https://raster.shields.io/github/contributors/sphinx-doc/sphinx-autobuild
       :alt: Contributors
       :target: https://github.com/sphinx-doc/sphinx-autobuild/graphs/contributors

    .. image:: https://raster.shields.io/github/commit-activity/y/sphinx-doc/sphinx-autobuild
       :alt: Commit activity
       :target: https://github.com/sphinx-doc/sphinx-autobuild/graphs/commit-activity

    .. image:: https://raster.shields.io/github/license/sphinx-doc/sphinx-autobuild
       :alt: Lizenz

`sphinx-autodoc-typehints <https://github.com/tox-dev/sphinx-autodoc-typehints>`_
    support for type hints for the Sphinx autodoc extension.

    .. image:: https://raster.shields.io/github/stars/tox-dev/sphinx-autodoc-typehints
       :alt: Stars
       :target: https://github.com/tox-dev/sphinx-autodoc-typehints

    .. image:: https://raster.shields.io/github/contributors/tox-dev/sphinx-autodoc-typehints
       :alt: Contributors
       :target: https://github.com/tox-dev/sphinx-autodoc-typehints/graphs/contributors

    .. image:: https://raster.shields.io/github/commit-activity/y/tox-dev/sphinx-autodoc-typehints
       :alt: Commit activity
       :target: https://github.com/tox-dev/sphinx-autodoc-typehints/graphs/commit-activity

    .. image:: https://raster.shields.io/github/license/tox-dev/sphinx-autodoc-typehints
       :alt: Lizenz

`nbsphinx <https://nbsphinx.readthedocs.io/>`_
    Jupyter notebooks in Sphinx

    .. image:: https://raster.shields.io/github/stars/spatialaudio/nbsphinx
       :alt: Stars
       :target: https://github.com/spatialaudio/nbsphinx

    .. image:: https://raster.shields.io/github/contributors/spatialaudio/nbsphinx
       :alt: Contributors
       :target: https://github.com/spatialaudio/nbsphinx/graphs/contributors

    .. image:: https://raster.shields.io/github/commit-activity/y/spatialaudio/nbsphinx
       :alt: Commit activity
       :target: https://github.com/spatialaudio/nbsphinx/graphs/commit-activity

    .. image:: https://raster.shields.io/github/license/spatialaudio/nbsphinx
       :alt: Lizenz

    .. seealso::
        `Embedding Widgets in the Sphinx HTML Documentation: Using the nbsphinx
        Project
        <https://ipywidgets.readthedocs.io/en/latest/embedding.html#using-the-nbsphinx-project>`_

`sphinxcontrib-mermaid <https://github.com/mgaitan/sphinxcontrib-mermaid>`_
    allows you to embed `Mermaid <http://mermaid.js.org/>`_ graphics in your
    documents.

    .. image:: https://raster.shields.io/github/stars/mgaitan/sphinxcontrib-mermaid
       :alt: Stars
       :target: https://github.com/mgaitan/sphinxcontrib-mermaid

    .. image:: https://raster.shields.io/github/contributors/mgaitan/sphinxcontrib-mermaid
       :alt: Contributors
       :target: https://github.com/mgaitan/sphinxcontrib-mermaid/graphs/contributors

    .. image:: https://raster.shields.io/github/commit-activity/y/mgaitan/sphinxcontrib-mermaid
       :alt: Commit activity
       :target: https://github.com/mgaitan/sphinxcontrib-mermaid/graphs/commit-activity

    .. image:: https://raster.shields.io/github/license/mgaitan/sphinxcontrib-mermaid
       :alt: Lizenz

`numpydoc <https://github.com/numpy/numpydoc>`_
    `NumPy <https://numpy.org/>`_ Sphinx extension

    .. image:: https://raster.shields.io/github/stars/numpy/numpydoc
       :alt: Stars
       :target: https://github.com/numpy/numpydoc

    .. image:: https://raster.shields.io/github/contributors/numpy/numpydoc
       :alt: Contributors
       :target: https://github.com/numpy/numpydoc/graphs/contributors

    .. image:: https://raster.shields.io/github/commit-activity/y/numpy/numpydoc
       :alt: Commit activity
       :target: https://github.com/numpy/numpydoc/graphs/commit-activity

    .. image:: https://raster.shields.io/github/license/numpy/numpydoc
       :alt: Lizenz

`Sphinx-Needs <https://sphinx-needs.readthedocs.io/>`_
    allows the definition, linking and filtering of need objects, such as
    requirements and test cases.

    .. image:: https://raster.shields.io/github/stars/useblocks/sphinx-needs
       :alt: Stars
       :target: https://github.com/useblocks/sphinx-needs

    .. image:: https://raster.shields.io/github/contributors/useblocks/sphinx-needs
       :alt: Contributors
       :target: https://github.com/useblocks/sphinx-needs/graphs/contributors

    .. image:: https://raster.shields.io/github/commit-activity/y/useblocks/sphinx-needs
       :alt: Commit activity
       :target: https://github.com/useblocks/sphinx-needs/graphs/commit-activity

    .. image:: https://raster.shields.io/github/license/useblocks/sphinx-needs
       :alt: Lizenz

`jupyter-sphinx <https://github.com/jupyter/jupyter-sphinx>`_
    enables the rendering of interactive Jupyter widgets in Sphinx.

    .. image:: https://raster.shields.io/github/stars/jupyter/jupyter-sphinx
       :alt: Stars
       :target: https://github.com/jupyter/jupyter-sphinx

    .. image:: https://raster.shields.io/github/contributors/jupyter/jupyter-sphinx
       :alt: Contributors
       :target: https://github.com/jupyter/jupyter-sphinx/graphs/contributors

    .. image:: https://raster.shields.io/github/commit-activity/y/jupyter/jupyter-sphinx
       :alt: Commit activity
       :target: https://github.com/jupyter/jupyter-sphinx/graphs/commit-activity

    .. image:: https://raster.shields.io/github/license/jupyter/jupyter-sphinx
       :alt: Lizenz

    .. seealso::
        `Embedding Widgets in the Sphinx HTML Documentation: Using the Jupyter
        Sphinx Extension
        <https://ipywidgets.readthedocs.io/en/latest/embedding.html#using-the-jupyter-sphinx-extension>`_

`Releases <https://github.com/bitprophet/releases>`_
    writes a :file:`CHANGELOG` file.

    .. image:: https://raster.shields.io/github/stars/bitprophet/releases
       :alt: Stars
       :target: https://github.com/bitprophet/releases

    .. image:: https://raster.shields.io/github/contributors/bitprophet/releases
       :alt: Contributors
       :target: https://github.com/bitprophet/releases/graphs/contributors

    .. image:: https://raster.shields.io/github/commit-activity/y/bitprophet/releases
       :alt: Commit activity
       :target: https://github.com/bitprophet/releases/graphs/commit-activity

    .. image:: https://raster.shields.io/github/license/bitprophet/releases
       :alt: Lizenz

`Sphinx Lint <https://github.com/sphinx-contrib/sphinx-lint>`_
    based on `rstlint.py
    <https://github.com/python/cpython/blob/e0433c1e7/Doc/tools/rstlint.py>`_
    from CPython.

    .. image:: https://raster.shields.io/github/stars/sphinx-contrib/sphinx-lint
       :alt: Stars
       :target: https://github.com/sphinx-contrib/sphinx-lint

    .. image:: https://raster.shields.io/github/contributors/sphinx-contrib/sphinx-lint
       :alt: Contributors
       :target: https://github.com/sphinx-contrib/sphinx-lint/graphs/contributors

    .. image:: https://raster.shields.io/github/commit-activity/y/sphinx-contrib/sphinx-lint
       :alt: Commit activity
       :target: https://github.com/sphinx-contrib/sphinx-lint/graphs/commit-activity

    .. image:: https://raster.shields.io/github/license/sphinx-contrib/sphinx-lint
       :alt: Lizenz

`sphinx-intl <https://pypi.org/project/sphinx-intl/>`_
    Sphinx extension for translations.

    .. image:: https://raster.shields.io/github/stars/sphinx-doc/sphinx-intl
       :alt: Stars
       :target: https://github.com/sphinx-doc/sphinx-intl

    .. image:: https://raster.shields.io/github/contributors/sphinx-doc/sphinx-intl
       :alt: Contributors
       :target: https://github.com/sphinx-doc/sphinx-intl/graphs/contributors

    .. image:: https://raster.shields.io/github/commit-activity/y/sphinx-doc/sphinx-intl
       :alt: Commit activity
       :target: https://github.com/sphinx-doc/sphinx-intl/graphs/commit-activity

    .. image:: https://raster.shields.io/github/license/sphinx-doc/sphinx-intl
       :alt: Lizenz

`sphinx-jsonschema <https://github.com/lnoor/sphinx-jsonschema>`_
    displays a `JSON Schema <https://json-schema.org>`_ in the Sphinx
    documentation.

    .. image:: https://raster.shields.io/github/stars/lnoor/sphinx-jsonschema
       :alt: Stars
       :target: https://github.com/lnoor/sphinx-jsonschema

    .. image:: https://raster.shields.io/github/contributors/lnoor/sphinx-jsonschema
       :alt: Contributors
       :target: https://github.com/lnoor/sphinx-jsonschema/graphs/contributors

    .. image:: https://raster.shields.io/github/commit-activity/y/lnoor/sphinx-jsonschema
       :alt: Commit activity
       :target: https://github.com/lnoor/sphinx-jsonschema/graphs/commit-activity

    .. image:: https://raster.shields.io/github/license/lnoor/sphinx-jsonschema
       :alt: Lizenz

`sphinx-toolbox <https://sphinx-toolbox.readthedocs.io/en/stable/index.html>`_
    Toolbox for Sphinx with many useful tools.

    .. image:: https://raster.shields.io/github/stars/sphinx-toolbox/sphinx-toolbox
       :alt: Stars
       :target: https://github.com/sphinx-toolbox/sphinx-toolbox

    .. image:: https://raster.shields.io/github/contributors/sphinx-toolbox/sphinx-toolbox
       :alt: Contributors
       :target: https://github.com/sphinx-toolbox/sphinx-toolbox/graphs/contributors

    .. image:: https://raster.shields.io/github/commit-activity/y/sphinx-toolbox/sphinx-toolbox
       :alt: Commit activity
       :target: https://github.com/sphinx-toolbox/sphinx-toolbox/graphs/commit-activity

    .. image:: https://raster.shields.io/github/license/sphinx-toolbox/sphinx-toolbox
       :alt: Lizenz

`Sphinx Sitemap Generator Extension <https://github.com/jdillard/sphinx-sitemap>`_
    generates multiversion and multilanguage `sitemaps
    <https://www.sitemaps.org/protocol.html>`_ for the HTML version.

    .. image:: https://raster.shields.io/github/stars/jdillard/sphinx-sitemap
       :alt: Stars
       :target: https://github.com/jdillard/sphinx-sitemap

    .. image:: https://raster.shields.io/github/contributors/jdillard/sphinx-sitemap
       :alt: Contributors
       :target: https://github.com/jdillard/sphinx-sitemap/graphs/contributors

    .. image:: https://raster.shields.io/github/commit-activity/y/jdillard/sphinx-sitemap
       :alt: Commit activity
       :target: https://github.com/jdillard/sphinx-sitemap/graphs/commit-activity

    .. image:: https://raster.shields.io/github/license/jdillard/sphinx-sitemap
       :alt: Lizenz

`sphinx-issues <https://pypi.org/project/sphinx-issues/>`_
    creates links to GitHub or GitLab issues, pull requests and user profiles.

    .. image:: https://raster.shields.io/github/stars/sloria/sphinx-issues
       :alt: Stars
       :target: https://github.com/sloria/sphinx-issues

    .. image:: https://raster.shields.io/github/contributors/sloria/sphinx-issues
       :alt: Contributors
       :target: https://github.com/sloria/sphinx-issues/graphs/contributors

    .. image:: https://raster.shields.io/github/commit-activity/y/sloria/sphinx-issues
       :alt: Commit activity
       :target: https://github.com/sloria/sphinx-issues/graphs/commit-activity

    .. image:: https://raster.shields.io/github/license/sloria/sphinx-issues
       :alt: Lizenz

`Sphinx-pyreverse <https://github.com/sphinx-pyreverse/sphinx-pyreverse>`_
    creates a UML diagram of Python modules.

    .. image:: https://raster.shields.io/github/stars/sphinx-pyreverse/sphinx-pyreverse
       :alt: Stars
       :target: https://github.com/sphinx-pyreverse/sphinx-pyreverse

    .. image:: https://raster.shields.io/github/contributors/sphinx-pyreverse/sphinx-pyreverse
       :alt: Contributors
       :target: https://github.com/sphinx-pyreverse/sphinx-pyreverse/graphs/contributors

    .. image:: https://raster.shields.io/github/commit-activity/y/sphinx-pyreverse/sphinx-pyreverse
       :alt: Commit activity
       :target: https://github.com/sphinx-pyreverse/sphinx-pyreverse/graphs/commit-activity

    .. image:: https://raster.shields.io/github/license/sphinx-pyreverse/sphinx-pyreverse
       :alt: Lizenz

`Sphinx-Test-Reports <https://sphinx-test-reports.readthedocs.io/en/latest/>`_
    displays test results within Sphinx documentation.

    .. image:: https://raster.shields.io/github/stars/useblocks/sphinx-test-reports
       :alt: Stars
       :target: https://github.com/useblocks/sphinx-test-reports

    .. image:: https://raster.shields.io/github/contributors/useblocks/sphinx-test-reports
       :alt: Contributors
       :target: https://github.com/useblocks/sphinx-test-reports/graphs/contributors

    .. image:: https://raster.shields.io/github/commit-activity/y/useblocks/sphinx-test-reports
       :alt: Commit activity
       :target: https://github.com/useblocks/sphinx-test-reports/graphs/commit-activity

    .. image:: https://raster.shields.io/github/license/useblocks/sphinx-test-reports
       :alt: Lizenz

`Sphinx Gitstamp Generator Extension <https://github.com/jdillard/sphinx-gitstamp>`_
    inserts :doc:`Git <Python4DataScience:productive/git/index>` timestamps in
    context, for example in a `Jinja
    <https://jinja.palletsprojects.com/en/stable/>`_ template:

    .. code-block:: jinja

       {%- if gitstamp %} Diese Seite wurde zuletzt aktualisiert am {{ gitstamp }}. {%- endif %}

    .. image:: https://raster.shields.io/github/stars/jdillard/sphinx-gitstamp
       :alt: Stars
       :target: https://github.com/jdillard/sphinx-gitstamp

    .. image:: https://raster.shields.io/github/contributors/jdillard/sphinx-gitstamp
       :alt: Contributors
       :target: https://github.com/jdillard/sphinx-gitstamp/graphs/contributors

    .. image:: https://raster.shields.io/github/commit-activity/y/jdillard/sphinx-gitstamp
       :alt: Commit activity
       :target: https://github.com/jdillard/sphinx-gitstamp/graphs/commit-activity

    .. image:: https://raster.shields.io/github/license/jdillard/sphinx-gitstamp
       :alt: Lizenz

.. seealso::
    `sphinx-contrib <https://github.com/sphinx-contrib/>`_
        A repository of Sphinx extensions maintained by their respective authors.
    `sphinx-extensions <https://sphinx-extensions.readthedocs.io/en/latest/>`_
        Curated site with Sphinx extensions with live examples and their
        configuration.

Custom extensions
-----------------

Local extensions in a project should be specified relative to the documentation.
The corresponding path is specified in the Sphinx configuration file
:file:`docs/conf.py`. If your extension is located in the ``exts`` directory in
the file :file:`foo.py`, then the :file:`conf.py` file should look like this:

.. code-block:: python

    import sys
    import os

    sys.path.insert(0, os.path.abspath("exts"))

    extensions = ["foo", ...]

.. seealso::
    * `Developing extensions for Sphinx
      <https://www.sphinx-doc.org/en/master/extdev/>`_
    * `Application API
      <https://www.sphinx-doc.org/en/master/extdev/appapi.html>`_