Documentation
=============

The source for the documentation can be found in the ``docs/source``
directory of this repository. These source files are a combination of
ReStructured Text (rst) and Jupyter notebooks.

Editing source files
--------------------

* ReStructured Text: The rst files should be fairly straightforward to edit. Here is
  `a quick reference of rst syntax <https://docutils.sourceforge.io/docs/user/rst/quickref.html>`_.
  Some of the rst files also use `Sphinx autodoc <https://www.sphinx-doc.org/en/master/usage/extensions/autodoc.html>`_.

* Jupyter Notebooks: The Jupyter notebooks are written in Python and should be written so that
  they are compatible with Python 3. If you need
  to reference another part of the documentation from a notebook, you will need
  to put that reference in a **raw** cell in the notebook, **not** a markdown
  cell.

Adding a new file to documentation
----------------------------------
If you add a new file (either rst or ipynb) make sure to link to it from the
relevant ``index.rst``.

Additionally, if you are adding a new notebook in the user guide, please add
the rst version of it to ``.gitignore``.


Building documentation locally
------------------------------

If you have made changes to the user guide or other notebooks that need to be
executed, please make sure you re-run all the documentation before committing.
While the documentation gets built automatically on Read The Docs, the notebooks do **not** get execute by Read The Docs -- they must be executed manually.
However, executing the notebooks is easy to do!

Our docs are built with `nbconvert <https://nbconvert.readthedocs.io/en/latest/>`_,
`Pandoc <https://pandoc.org/>`_, and `Sphinx <https://www.sphinx-doc.org/en/master/>`_.
To build the docs locally, run the following command::

    python tasks.py docs

This will perform a few different steps:

1. The notebooks are executed and converted to rst or html (the actual
   documentation notebooks will be converted to rst, and example notebooks will
   be converted to html) using the ``build_docs.py`` script.
2. The command line documentation is automatically generated using the
   ``autogen_command_line.py`` and ``autogen_config.py`` scripts.
3. The rst files are converted to html using Sphinx.

After running ``python tasks.py docs``, the resultant HTML files will be in
``docs/build/html``. You can open these files in your browser to preview what
the documentation will look like (note, however, that the theme used by Read
The Docs is different from the default Sphinx theme, so the styling will look
different).

Automatic builds
----------------
When a commit is made on the ``master`` branch, documentation is automatically
built by Read The Docs and rendered at
`nbgrader.readthedocs.org <https://nbgrader.readthedocs.io/en/stable/>`_.
