Documentation#
Overview#
All code must be documented and we follow these style conventions described here:
We recommend familiarizing yourself with this style.
Referring to other code#
To link to other methods, classes, or modules in sunpy you have to use backticks, for example:
`sunpy.map.GenericMap`
generates a link like this: sunpy.map.GenericMap
.
We use the sphinx setting default_role = 'obj'
so that you do not nor SHOULD NOT use the :class:
qualifier, but :func:
, :meth:
are different (more on this below).
Often, you don’t want to show the full package and module name. As long as the target is unambiguous you can simply leave them out:
`.GenericMap`
and the link still works: GenericMap
.
If there are multiple code elements with the same name (e.g. peek()
is a method in multiple classes), you’ll have to extend the definition:
`.GenericMap.peek` or `.CompositeMap.peek`
These will show up as GenericMap.peek
or CompositeMap.peek
.
To still show only the last segment you can add a tilde as prefix:
`~.GenericMap.peek` or `~.CompositeMap.peek`
Other packages can also be linked via intersphinx:
`numpy.mean`
will return this link: numpy.mean
.
This works for Python, Numpy and Astropy (full list is in docs/conf.py
).
With Sphinx, if you use :func:
or :meth:
, it will add closing brackets to the link.
If you get the wrong pre-qualifier, it will break the link, so we suggest that you double check if what you are linking is a method or a function.
:class:`numpy.mean()`
:meth:`numpy.mean()`
:func:`numpy.mean()`
will return two broken links (“class” and “meth”) but “func” will work.
sunpy-Specific Rules#
For all RST files, we enforce a one sentence per line rule and ignore the line length.
Standards on docstring length and style are enforced using docformatter:
docformatter -r -i --pre-summary-newline --make-summary-multi-line
Heading style is the following for all RST files:
* with overline, for titles
= for sections
- for subsections
^ for subsubsections
" for paragraphs
Anchors for each page should follow this format:
sunpy-<section>-<subsection>-<summary of title>
., e.g.,sunpy-tutorial-acquiring-data-index
.Use of
.. code-block:
is required for all code examples.
Documenting Data Sources#
Subclasses of GenericMap
or TimeSeries
must provide a detailed docstring providing an overview of the data source that the object represents.
In order to maintain consistency and completeness, the following information must be provided by a data source docstring, if available, and preferably in the following order:
the name of the mission and instrument and the institution that built it
short description of the instrument (e.g. Cassegrain reflector, Wolter-1 grazing incidence x-ray, coronagraph) including the type of detector
description of the platform (e.g. satellite in 28 deg inclined orbit, a telescope on the summit of Mauna Kea in Hawaii)
description of the primary purpose or science goals of the instrument.
list of all wavelength(s) or passbands in appropriate units
description of the emission processes which dominate in those passbands
appropriate measurement properties such as field of view, angular resolution, time resolution
description of the operational concept (e.g. operates 24/7, observes from 7 am to 5 pm UT) including mention of unusual operations scenarios (e.g. calibration seasons, eclipse seasons)
the start and end of the data set
In addition, a reference section must be provided with links to the following resources, if available,
the mission web page
the instrument web page
relevant wikipedia page(s)
relevant user guide(s)
the mission paper and instrument paper
information to interpret metadata keywords such as FITS header reference
the data archive
Examples can be found in any class defined in any Python file in sunpy/map/sources/
such as AIAMap
.
Sphinx#
All of the sunpy documentation (like this page) is built by Sphinx, which is a tool especially well-suited for documenting Python projects. Sphinx works by parsing files written using a a Mediawiki-like syntax called reStructuredText. In addition to parsing static files of reStructuredText, Sphinx can also be told to parse code comments. In fact, in addition to what you are reading right now, the Python documentation was also created using Sphinx.
Usage#
All of the sunpy documentation is contained in the “docs” folder and code documentation strings. The examples from the example gallery can be found in the “examples” folder.
In the root directory run:
tox -e build_docs-gallery
This will generate HTML documentation for sunpy in the “docs/_build/html” directory. You can open the “index.html” file to browse the final product. The gallery examples are located under “docs/_build/html/generated/gallery”. Sphinx builds documentation iteratively, only adding things that have changed.
If you want to build the documentation without executing the gallery examples, i.e. to reduce build times while working on other sections of the documentation you can run:
tox -e build_docs
If you’d like to start from scratch (i.e., remove the tox cache) then change to the docs/
directory and run:
make clean
cd ..
tox -r -e build_docs-gallery
To build the documentation in your current python environment you must have all the dependencies specified in pyproject.toml
installed (pip install -e .[docs,docs-gallery]
).
Then change to the docs/
directory and run:
make html
For more information on how to use Sphinx, consult the Sphinx documentation.
Special Sphinx directives#
minigallery
directive#
Sphinx will automatically record which functions, classes, etc. are used in each gallery example. In the documentation, you can insert a mini-gallery of the subset of the gallery examples that uses a particular function, class, etc. For example, the following RST block:
.. minigallery:: sunpy.coordinates.RotatedSunFrame
produces this mini-gallery:
Comparing differential-rotation models
Differentially rotating a coordinate
Overlaying differentially rotated gridlines
If you want to specify more than one object, separate them by spaces. This is particularly useful if you need to cover multiple namespaces in which an object may be accessed, e.g.:
.. minigallery:: sunpy.coordinates.RotatedSunFrame sunpy.coordinates.metaframes.RotatedSunFrame
generate
directive#
In rare circumstances, one may want to insert “raw” HTML directly into the pages written by Sphinx.
For HTML that is statically available (i.e., already written in some form), one can use the “raw” directive.
For HTML that is generated by Python code, sunpy provides the custom directive generate
.
Here’s an example RST block:
.. generate:: html
:html_border:
import os
from sunpy.data.sample import file_dict
print("<table>")
for key, value in file_dict.items():
print(f"<tr><th>{key}</th><td>{os.path.basename(value)}</td></tr>")
print("</table>")
to insert the following HTML table:
AIA_094_IMAGE | AIA20110607_063305_0094_lowres.fits |
---|---|
AIA_131_IMAGE | AIA20110607_063301_0131_lowres.fits |
AIA_1600_IMAGE | AIA20110607_063305_1600_lowres.fits |
AIA_1600_VENUS_IMAGE | aia_lev1_1600a_2012_06_06t04_07_29_12z_image_lev1_lowres.fits |
AIA_171_IMAGE | AIA20110607_063302_0171_lowres.fits |
AIA_171_ROLL_IMAGE | aiacalibim5.fits |
AIA_193_CUTOUT01_IMAGE | AIA20110607_063307_0193_cutout.fits |
AIA_193_CUTOUT02_IMAGE | AIA20110607_063931_0193_cutout.fits |
AIA_193_CUTOUT03_IMAGE | AIA20110607_064555_0193_cutout.fits |
AIA_193_CUTOUT04_IMAGE | AIA20110607_065219_0193_cutout.fits |
AIA_193_CUTOUT05_IMAGE | AIA20110607_065843_0193_cutout.fits |
AIA_193_IMAGE | AIA20110607_063307_0193_lowres.fits |
AIA_193_JUN2012 | AIA20120601_000007_0193_lowres.fits |
AIA_211_IMAGE | AIA20110607_063302_0211_lowres.fits |
AIA_304_IMAGE | AIA20110607_063334_0304_lowres.fits |
AIA_335_IMAGE | AIA20110607_063303_0335_lowres.fits |
AIA_STEREOSCOPIC_IMAGE | aia_lev1_171a_2023_07_06t00_05_33_35z_image_lev1.fits |
CALLISTO_SPECTRUM | BIR_20110607_062400_10.fit |
EIT_195_IMAGE | eit_l1_20110607_203753.fits |
EUVI_STEREOSCOPIC_IMAGE | 20230706_000525_n4eua.fts |
EVE_TIMESERIES | 20110607_EVE_L0CS_DIODES_1m.txt |
GBM_TIMESERIES | glg_cspec_n5_110607_v00.pha |
GOES_XRS_TIMESERIES | go1520110607.fits |
HMI_LOS_IMAGE | HMI20110607_063211_los_lowres.fits |
LOFAR_IMAGE | LOFAR_70MHZ_20190409_131136.fits |
LYRA_LEVEL3_TIMESERIES | lyra_20110607-000000_lev3_std.fits |
NORH_TIMESERIES | tca110607.fits |
RHESSI_IMAGE | hsi_image_20110607_063300.fits |
RHESSI_TIMESERIES | hsi_obssumm_20110607_025.fits |
SRS_TABLE | 20110607SRS.txt |
STEREO_A_195_JUN2012 | 20120601_000530_n4eua.fits |
STEREO_B_195_JUN2012 | 20120601_000530_n4eub.fits |
SWAP_LEVEL1_IMAGE | swap_lv1_20110607_063329.fits |
Troubleshooting#
Sphinx can be very particular about formatting, and the warnings and errors aren’t always obvious.
Below are some commonly-encountered warning/error messages along with a human-readable translation:
WARNING: Duplicate explicit target name: “xxx”.
If you reference the same URL, etc more than once in the same document sphinx will complain. To avoid, use double-underscores instead of single ones after the URL.
ERROR: Malformed table. Column span alignment problem at line offset n
Make sure there is a space before and after each colon in your class and function docs (e.g. attribute : type, instead of attribute: type). Also, for some sections (e.g. Attributes) numpydoc seems to complain when a description spans more than one line, particularly if it is the first attribute listed.
WARNING: Block quote ends without a blank line; unexpected unindent.
Lists should be indented one level from their parents.
ERROR: Unknown target name: “xxx”
In addition to legitimate errors of this type, this error will also occur when variables have a trailing underscore, e.g., xxx_
.
WARNING: Explicit markup ends without a blank line; unexpected unindent.
This usually occurs when the text following a directive is wrapped to the next line without properly indenting a multi-line text block.
WARNING: toctree references unknown document ‘…’ / WARNING: toctree contains reference to nonexisting document
This pair of errors is due to the way numpydoc scrapes class members.