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.
Raw data
{
"_id": null,
"home_page": "https://github.com/astropy/sphinx-astropy",
"name": "sphinx-astropy",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.9",
"maintainer_email": null,
"keywords": null,
"author": "The Astropy Developers",
"author_email": "astropy.team@gmail.com",
"download_url": "https://files.pythonhosted.org/packages/2f/d4/7f653bf677d253bf569e40d19da5effaed9c89d107f8b130d05a88e9dde2/sphinx_astropy-1.10.tar.gz",
"platform": null,
"description": "About\n=====\n\n.. image:: https://zenodo.org/badge/119399685.svg\n :target: https://zenodo.org/badge/latestdoi/119399685\n :alt: Zenodo DOI\n\n.. image:: https://github.com/astropy/sphinx-astropy/actions/workflows/python-tests.yml/badge.svg\n :target: https://github.com/astropy/sphinx-astropy/actions/workflows/python-tests.yml\n :alt: CI Status\n\nThis 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.\n\nSphinx configuration\n--------------------\n\nThe default Sphinx configuration can be imported by putting:\n\n.. code-block:: python\n\n from sphinx_astropy.conf import *\n\nat 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:\n\n.. code-block:: python\n\n try:\n from sphinx_astropy.conf import *\n except ImportError:\n print('ERROR: the documentation requires the sphinx-astropy package to be installed')\n sys.exit(1)\n\nDependencies/extensions\n-----------------------\n\nInstalling **sphinx-astropy** will automatically install (if not already present):\n\n* `Sphinx <http://www.sphinx-doc.org>`_\n\n* `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`.\n\n* `sphinx-automodapi <http://sphinx-automodapi.readthedocs.io>`_ - an extension that makes it easy to automatically generate API documentation.\n\n* `sphinx-gallery <https://sphinx-gallery.readthedocs.io/en/latest/>`_ - an extension to generate example galleries\n\n* `numpydoc <https://numpydoc.readthedocs.io>`_ - an extension to parse docstrings in NumpyDoc format\n\n* `pillow <https://pillow.readthedocs.io/en/latest/>`_ - a package to deal with\n images, used by some examples in the astropy core documentation.\n\n* `pytest-doctestplus <https://github.com/astropy/pytest-doctestplus/>`_ - providing the 'doctestplus' extension to skip code snippets in narrative documentation.\n\npydata-sphinx-theme (confv2)\n^^^^^^^^^^^^^^^^^^^^^^^^^^^^\n\nTo use the new `pydata-sphinx-theme` with `sphinx_astropy.conf.v2`, you have to install\nthe optional `[confv2]` dependencies::\n\n pip install sphinx-astropy[confv2]\n\nThat would pull in the following as well:\n\n* `pydata-sphinx-theme <https://github.com/pydata/pydata-sphinx-theme/>`_ - a clean, three-column,\n Bootstrap-based Sphinx theme by and for the `PyData community <https://pydata.org/>`_.\n\n* `sphinx-copybutton <https://github.com/executablebooks/sphinx-copybutton>`_ - a small Sphinx\n extension to add a \"copy\" button to code blocks.\n",
"bugtrack_url": null,
"license": "BSD",
"summary": "Sphinx extensions and configuration specific to the Astropy project",
"version": "1.10",
"project_urls": {
"Homepage": "https://github.com/astropy/sphinx-astropy"
},
"split_keywords": [],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "9b5f310bca0b125d3e3919708311339a3dd518136b9dd70a8c7d15fa2ad4a86c",
"md5": "bfb7574670d1e3a1bf7c0bfc813178e7",
"sha256": "27da035a4154e10a92e04201fc5aad0c582d1b7a58b0d7dd6a705e56bd2fc0f3"
},
"downloads": -1,
"filename": "sphinx_astropy-1.10-py3-none-any.whl",
"has_sig": false,
"md5_digest": "bfb7574670d1e3a1bf7c0bfc813178e7",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.9",
"size": 24206,
"upload_time": "2025-08-06T17:56:36",
"upload_time_iso_8601": "2025-08-06T17:56:36.371955Z",
"url": "https://files.pythonhosted.org/packages/9b/5f/310bca0b125d3e3919708311339a3dd518136b9dd70a8c7d15fa2ad4a86c/sphinx_astropy-1.10-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "2fd47f653bf677d253bf569e40d19da5effaed9c89d107f8b130d05a88e9dde2",
"md5": "61f702f3b73a165e3b74b5e36cda3ef9",
"sha256": "408aa180d8de0d3cf3c91ce4abd83701b09457b722804b7194e6692e2fe534e2"
},
"downloads": -1,
"filename": "sphinx_astropy-1.10.tar.gz",
"has_sig": false,
"md5_digest": "61f702f3b73a165e3b74b5e36cda3ef9",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.9",
"size": 20562,
"upload_time": "2025-08-06T17:56:37",
"upload_time_iso_8601": "2025-08-06T17:56:37.254598Z",
"url": "https://files.pythonhosted.org/packages/2f/d4/7f653bf677d253bf569e40d19da5effaed9c89d107f8b130d05a88e9dde2/sphinx_astropy-1.10.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-08-06 17:56:37",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "astropy",
"github_project": "sphinx-astropy",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"tox": true,
"lcname": "sphinx-astropy"
}
JSON
