1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
|
.. _documentation-guidelines:
*********************
Writing Documentation
*********************
High-quality, consistent documentation for astronomy code is one of the major
goals of the Astropy Project. Hence, we describe our documentation procedures
and rules here. For the astropy core project and coordinated packages we try to
keep to these as closely as possible, and we encourage affiliated packages to
also adhere to these as they encourage useful documentation, a characteristic
often lacking in professional astronomy software.
Adding a Git Commit
===================
When your changes only affect documentation (i.e., docstring or RST files)
and do not include any code snippets that require doctest to run, you may
add a ``[ci skip]`` in your commit message. For example::
git commit -m "Update documentation about this and that [ci skip]"
When this commit is pushed out to your branch associated with a pull request,
all CI will be skipped because it is not required. This is because the
the documentation build resides in RTD, which currently does not respect the
``[ci skip]`` directive.
However, due to branch protection rules, the merge button will be disabled
even though RTD build succeeds when ``[ci skip]`` is used. Please ping
``@astropy/devops-maintainers`` to review it, as they could override
the block.
Building the Documentation from source
======================================
For information about building the documentation from source, see
the :ref:`builddocs` section in the installation instructions.
Astropy Documentation Rules and 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.
* All documentation text should follow the :ref:`astropy-style-guide`.
* All documentation should be written using the `Sphinx`_
documentation tool.
* ReST substitutions are centralized in ``docs/conf.py::rst_epilog`` for
consistency across the documentation and docstrings. These should be used over
custom redefinitions; and new substitutions should probably be placed there.
* The `package template <https://github.com/astropy/package-template>`_ provides
a recommended general structure for documentation.
* Docstrings must be provided for all public classes, methods, and functions.
* Docstrings should follow the `numpydoc format
<https://numpydoc.readthedocs.io/en/latest/format.html>`_.
* References in docstrings, **including internal Astropy links**, should use the
`intersphinx format
<https://www.sphinx-doc.org/en/master/usage/extensions/intersphinx.html>`_.
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 affiliate packages using ``sphinx-astropy``'s intersphinx mapping,
the links resolve to the stable version of Astropy. For linking to the
development version, use the intersphinx target 'astropy-dev'.
* Examples and/or tutorials are strongly encouraged for typical use-cases of a
particular module or class.
* Any external package dependencies must be explicitly mentioned in the
documentation. They should also be recorded in the ``setup.cfg`` file in the
root of the astropy repository using an entry in ``extras_require``,
under ``all``.
* Configuration options using the :mod:`astropy.config` mechanisms must be
explicitly mentioned in the documentation.
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.
* sphinx-gallery_ - an extension to generate example galleries
* `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: http://www.sphinx-doc.org/
.. _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
.. _sphinx-gallery: https://sphinx-gallery.readthedocs.io
|
