:orphan: .. # This file is included. So it needs to be marked as orphan to suppress warnings. .. https://www.sphinx-doc.org/en/master/usage/restructuredtext/field-lists.html#metadata .. include:: dependencies.rst :start-after: :orphan: .. _documentation-guidelines: ************************ Documentation Guidelines ************************ High-quality, consistent documentation for astronomy code is one of the major goals of the Astropy Project. We encourage you to help us improve the documentation, and you do not have to be an expert on ``astropy`` to do so! If something in the docs does not make sense to you, updating the relevant section after you figure it out is a great way to contribute to Astropy and help others in the future. In this section we describe our documentation procedures and rules that apply to the ``astropy`` core package and coordinated packages. We encourage affiliated packages to do the same. Astropy Documentation Overview ============================== The documentation is written in **reStructuredText**, which is almost like writing in plain English, and built using Sphinx_. The Sphinx Documentation has an excellent `introduction to reST `_ that you should read. The Astropy documentation consists of two parts. The code docstrings provide a clear explanation of the usage of individual functions, classes and modules. These are collected by Sphinx into the API documentation. The narrative documentation is contained in the source code ``docs`` directory and provides a more tutorial-like overview of each sub-package together with other topical information like What's New, Installation, Developer documentation, etc. .. _OpenAstronomy Packaging Guide: https://packaging-guide.openastronomy.org/en/latest The `OpenAstronomy Packaging Guide`_ provides a recommended general structure for documentation. Astropy Documentation Guidelines ================================ This section describes the standards for documentation that any contribution being considered for integration into the core package should follow, as well as the standard Astropy docstring format. * Documentation text should follow the :external+astropy:ref:`astropy-style-guide`. * Docstrings must be provided for all public classes, methods, and functions, and be written using the `numpydoc format `_. * References in docstrings, **including internal Astropy links**, should use the `intersphinx format `_. For example a link to the Astropy section on unit equivalencies would be ``:ref:`astropy:unit_equivalencies```. When built in Astropy, links starting with 'astropy' resolve to the current build. In affiliated packages using the ``sphinx-astropy`` intersphinx mapping, the links resolve to the stable version of Astropy. For linking to the development version, use direct URL linking. * Examples and/or tutorials are strongly encouraged for typical use-cases of a particular module or class. * Optional package dependencies should be documented where feasible. * Configuration options using the :mod:`astropy.config` mechanisms must be explicitly mentioned in the documentation. .. _builddocs: Building the Documentation from Source ====================================== There are two ways to build the Astropy documentation. The first way is to execute the following ``tox`` command from within the ``astropy`` source directory:: tox -e build_docs With this method you do not need to install any of the documentation dependencies. The documentation will be built in the ``docs/_build/html`` directory, and can be read by pointing a web browser to ``docs/_build/html/index.html``. The second method is to build the documentation manually. This requires that you are working in an isolated development environment as described in :ref:`contributing_environment`. The benefit of this method is that often you can rebuild the docs fairly quickly after making changes. :: cd docs make html The documentation will be generated in the same location. In some cases if you make changes they will not be reflected in the build output and you need to start over after running ``make clean``. To use multiple cores for building faster, run:: SPHINXOPTS="-j auto" make html Dependencies ------------ Here we describe the key dependencies for building the documentation. These are provided by the ``docs`` optional dependencies in the ``astropy`` package (see the ``[docs]`` list in ``[project.optional-dependencies]`` in ``pyproject.toml``). The `sphinx-astropy `_ package provides configuration common to packages in the Astropy ecosystem and serves as a way to automatically get the other main dependencies, including: * `Sphinx `_ - the main package we use to build the documentation * `astropy-sphinx-theme `_ - the default 'bootstrap' theme used by ``astropy`` and a number of affiliated packages * sphinx-automodapi_ - an extension that makes it easy to automatically generate API documentation * |numpydoc| - an extension to parse docstrings in NumPyDoc format * `Graphviz `_ - generate inheritance graphs (available as a conda package or a system install but not in pip) .. Note:: Both of the ``pip`` install methods above do not include `Graphviz `_. If you do not install this package separately then the documentation build process will produce a very large number of lengthy warnings (which can obscure bona fide warnings) and also not generate inheritance graphs. Reporting Issues/Requesting Features ------------------------------------ As mentioned above, building the documentation depends on a number of Sphinx extensions and other packages. Since it is not always possible to know which package is causing issues or would need to have a new feature implemented, you can open an issue in the `core astropy package issue tracker `_. However, if you wish, you can also open issues in the repositories for some of the dependencies: * For requests/issues related to the appearance of the docs (e.g. related to the CSS), you can open an issue in the `astropy-sphinx-theme issue tracker `_. * For requests/issues related to the auto-generated API docs which appear to be general issues rather than an issue with a specific docstring, you can use the `sphinx-automodapi issue tracker `_. * For issues related to the default configuration (e.g which extensions are enabled by default), you can use the `sphinx-astropy issue tracker `_. Details for Package Maintainers =============================== Following is useful information for package maintainers who are using the Astropy documentation infrastructure and may want to customize it for their package. Sphinx Documentation Themes --------------------------- An Astropy Project Sphinx HTML theme is included in the astropy-sphinx-theme_ package. This allows the theme to be used by both Astropy and affiliated packages. The theme is activated by setting the theme in the global Astropy sphinx configuration in sphinx-astropy_, which is imported in the sphinx configuration of both Astropy and affiliated packages. A different theme can be used by overriding a few sphinx configuration variables set in the global configuration. * To use a different theme, set ``html_theme`` to the name of a desired builtin Sphinx theme or a custom theme in ``package-name/docs/conf.py`` (where ``'package-name'`` is "astropy" or the name of the affiliated package). * To use a custom theme, additionally: place the theme in ``package-name/docs/_themes`` and add ``'_themes'`` to the ``html_theme_path`` variable. See the Sphinx documentation for more details on theming. Sphinx extensions ----------------- The documentation build process for Astropy uses a number of sphinx extensions which are all installed automatically when installing sphinx-astropy_. These facilitate easily documenting code in a homogeneous and readable way. The main extensions used are: * sphinx-automodapi_ - an extension that makes it easy to automatically generate API documentation. * |numpydoc| - an extension to parse docstrings in NumpyDoc format In addition, the sphinx-astropy_ includes a few small extensions: * ``sphinx_astropy.ext.edit_on_github`` - an extension to add 'Edit on GitHub' links to documentation pages. * ``sphinx_astropy.ext.changelog_links`` - an extension to add links to pull requests when rendering the changelog. * ``sphinx_astropy.ext.doctest`` - an extension that makes it possible to add metadata about doctests inside ``.rst`` files .. _sphinx-automodapi: https://github.com/astropy/sphinx-automodapi .. _astropy-sphinx-theme: https://github.com/astropy/astropy-sphinx-theme .. _sphinx-astropy: https://github.com/astropy/sphinx-astropy