.. _documentation:
Documenting your Package
========================
There are two main ways to document your project, both of
which are essential: :ref:`docstrings` and :ref:`narrative`.
.. _docstrings:
Docstrings
----------
First, public functions, methods, and classes
in your package should include *docstrings*, which are strings
attached to those objects which the user can access interactively
using e.g. ``help()`` and which can also be retrieved by automated
tools. See `PEP 257 - Docstring Conventions `_
for a high-level overview of what docstrings are. We recommend adopting
the `numpydoc `_
format for docstrings. An example of such a docstring is::
def foo(var, long_var_name='hi'):
"""A one-line summary that does not use variable names.
Several sentences providing an extended description. Refer to
variables using back-ticks, e.g. `var`.
Parameters
----------
var : int
The type above can either refer to an actual Python type
(e.g. ``int``), or describe the type of the variable in more
detail, e.g. ``(N,) ndarray`` or ``array_like``.
long_var_name : {'hi', 'ho'}, optional
Choices in brackets, default first when optional.
Returns
-------
out : type
Explanation of `out`.
"""
These docstrings should be included in the Python files alongside the Python
objects they document.
.. _narrative:
Narrative Documentation
-----------------------
Second, you should write a set of narrative documentation which functions as a
user guide, such as http://docs.astropy.org or http://docs.sunpy.org. For this
we recommend making use
of the `Sphinx `_ tool and storing your documentation
inside a ``docs`` directory.
To set this up, first install the Sphinx package, then create a ``docs`` directory
and run ``sphinx-quickstart`` inside it::
$ mkdir docs
$ cd docs
$ sphinx-quickstart
We recommend answering ``n`` for the question of whether to separate
source and build directories. Once you have run this, you should see the following files
inside your ``docs`` directory::
Makefile
conf.py
index.rst
make.bat
The ``index.rst`` file is the root of your documentation. You can start writing content
in it and you can also start adding more ``.rst`` pages if needed. If you haven't used
Sphinx before, we recommend taking a look at their
`Getting Started `_ guide.
.. _automodapi:
Including docstrings in the narrative documentation
---------------------------------------------------
As part of the narrative documentation, it is also common practice to include an
Application programming interface (API) page which lists the available classes,
methods, and functions in your package. Thankfully, if you've defined your docstrings
as described in :ref:`docstrings`, then this can be automated using the
`sphinx-automodapi `_
package. See the documentation of that package for more details, but briefly,
you will need to add ``'sphinx_automodapi.automodapi'`` to the ``extensions``
variable in your ``conf.py`` file:
.. code-block:: python
extensions = ['sphinx_automodapi.automodapi']
In addition, if you use the numpydoc format for your docstrings, as recommended in :ref:`docstrings`,
you will need to include either ``'numpydoc'`` or ``'sphinx.ext.napoleon'`` in
the list of ``extensions`` (both packages provide a way to parse numpydoc-style
docstrings). If you use the numpydoc package, you will need to also include:
.. code-block:: python
numpydoc_show_class_members = False
in your ``conf.py`` file.
Declaring dependencies for documentation
----------------------------------------
To make it easier for contributors to get set up with the dependencies
required to build the documentation, as well as to make it easier to
configure automated builds (whether for :ref:`ReadTheDocs `
or :ref:`tox `), you should define an ``[project.optional-dependencies]`` section in
your ``pyproject.toml`` file named ``docs`` which lists the dependencies
required to build the documentation (not including dependencies already
mentioned in ``dependencies``):
.. code-block:: toml
[project.optional-dependencies]
docs = [
"sphinx",
"sphinx-automodapi",
"numpydoc",
]
This will then allow contributors to type::
pip install -e .[docs]
to install the package in developer/editable mode along with the documentation
dependencies.
.. _readthedocs:
Setting up ReadTheDocs
----------------------
`ReadTheDocs `__ is a platform that will build
documentation with sphinx and will then host it, and is used by many of
the Scientific Python packages. The easiest way to configure the build
is to add a file called ``.readthedocs.yml`` to your package, and we
recommend starting off with:
.. code-block:: yaml
version: 2
build:
image: latest
tools:
python: 3.9
python:
install:
- method: pip
path: .
extra_requirements:
- docs
Once you have added this to your repository, you can then import your
package into ReadTheDocs as described in `this guide
`_.
.. _plot_directive:
Add plots to your documentation
-------------------------------
A plot is worth *many* words, and sometimes documentation
can demonstrate the uses and advantages of using a given
package much more efficiently than narrative docs. Matplotlib,
for example, has made this quite straightforward with the
`plot directive `_.
To add a plot to your Sphinx documentation, add the following string to the
``extensions`` list in your ``docs/conf.py`` file:
.. code-block:: python
extensions = [
... # preserve your other extensions here, then add:
"matplotlib.sphinxext.plot_directive"
]
To make use of this extension, you will also need to add ``matplotlib`` to your
``tox.ini`` file:
.. code-block:: ini
deps =
# preserve your other deps here, then add:
matplotlib
Now you can add plots to your Sphinx docs by adding a block like
the following to your narrative docs:
.. code-block:: rst
Here's a plot:
.. plot::
import matplotlib.pyplot as plt
x, y = [1, 2, 3], [4, 5, 6]
plt.figure()
plt.plot(x, y)
By default, sphinx and matplotlib will render the figure defined by the
Python code in the ``.. plot::`` block, without the source code. Full documentation
for the configuration settings for the plot directive can be found in the
`matplotlib docs `_.