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": "",
"docs_url": null,
"requires_python": ">=3.7",
"maintainer_email": "",
"keywords": "",
"author": "The Astropy Developers",
"author_email": "astropy.team@gmail.com",
"download_url": "https://files.pythonhosted.org/packages/18/ee/957984621943eaa47497be959cc6695ae775745525e5fe9d4ff8174678cc/sphinx-astropy-1.9.1.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.9.1",
"project_urls": {
"Homepage": "https://github.com/astropy/sphinx-astropy"
},
"split_keywords": [],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "4add1487887b8fc3be42fb0cf896f4683ea1d21035485407498e5c1d51325987",
"md5": "17a3461855bed0edf37e84796f11cfd2",
"sha256": "0a6be6addb511c3d83647763608ef4fb9254dbc25ae04504837b3b1139c4b130"
},
"downloads": -1,
"filename": "sphinx_astropy-1.9.1-py3-none-any.whl",
"has_sig": false,
"md5_digest": "17a3461855bed0edf37e84796f11cfd2",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.7",
"size": 23765,
"upload_time": "2023-06-07T18:45:30",
"upload_time_iso_8601": "2023-06-07T18:45:30.297100Z",
"url": "https://files.pythonhosted.org/packages/4a/dd/1487887b8fc3be42fb0cf896f4683ea1d21035485407498e5c1d51325987/sphinx_astropy-1.9.1-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "18ee957984621943eaa47497be959cc6695ae775745525e5fe9d4ff8174678cc",
"md5": "da84468f9a8395216a22f8bdf292d43b",
"sha256": "7931c795f445caee38f98754afd75fe7393db7df2c4dcc860f94a011fb162454"
},
"downloads": -1,
"filename": "sphinx-astropy-1.9.1.tar.gz",
"has_sig": false,
"md5_digest": "da84468f9a8395216a22f8bdf292d43b",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.7",
"size": 19277,
"upload_time": "2023-06-07T18:45:31",
"upload_time_iso_8601": "2023-06-07T18:45:31.599285Z",
"url": "https://files.pythonhosted.org/packages/18/ee/957984621943eaa47497be959cc6695ae775745525e5fe9d4ff8174678cc/sphinx-astropy-1.9.1.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2023-06-07 18:45:31",
"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
