Documentation Guidelines

This document describes the documentation requirements and guidelines to be followed during the development of PlasmaPy and affiliated packages.

Building documentation

Documentation is built from the master branch on every commit pushed to it.

Using sphinx within the project

To build docs locally, run sphinx-build docs docs/_build from within the main PlasmaPy repository directory, then open docs/_build/index.html with your browser of choice.

Do try to solve warnings in documentation when writing your code.

Docstrings

  • All public classes, methods, and functions should have docstrings.
  • PlasmaPy uses the numpydoc standard for docstrings.
  • Docstrings must be raw string literals if they contain backslashes. A raw string literal is denoted by having an r immediately precede quotes or triple quotes:
r""" I did not like unstable eigenfunctions at first, but then they
grew on me.

"""
  • Simple functions may need only a one-line docstring.

Narrative Documentation

  • Each subpackage must have narrative documentation describing its use.