.. _contributing_to_the_documentation:

Contributing to the Documentation
=================================

This section explains the process for contributing specifically to SweetPea's
documentation.


Installing Dependencies
-----------------------

First, you must have installed SweetPea as explained in
:ref:`configuring_development_environment`. After that's done, you'll need to
install Sphinx and the Read the Docs theme to be able to build the
documentation::

    $ pip install sphinx sphinx-rtd-theme


.. _building_the_documentation:

Building the Documentation
--------------------------

To build the documentation locally, navigate to the `docs/` directory in the
repository and start the build process::

    $ make html

(Sphinx supports alternate build targets, but we only use the HTML target.)

This will generate the documentation website locally, which will be located in
`docs/_build/` with the root page of the site at `docs/_build/index.html`. You
can open that file in your web browser of choice to browse your local copy of
the documentation.

.. note::

    You should *never* be directly manipulating code in `docs/_build/`! These
    files are the result of the building process. Instead, edit the source code
    in `docs/_source` and run the build process.

Sphinx will output helpful errors and messages during the build process, with
errors written to the terminal in red text. We only consider builds with no red
text to be fully successful, so please strive to always ensure your build
process works flawlessly!


Automatic vs Manual Documentation
---------------------------------

Some of SweetPea's documentation pages are written manually, while many are
generated automatically from in-code documentation.

The automatically generated code will be put in `docs/_source/api/` by the
`sphinx-apidoc` tool as part of the build process.

.. important::

    Do not contribute code to `docs/_source/api/`! Its contents are
    automatically deleted and regenerated by the build process.

The manual documentation is located in the rest of the `docs/_source/`
directory, with most of the content in the `docs/_source/guide/` subdirectory.


Contributing to the Automatic Documentation
-------------------------------------------

The automatic documentation is generated from docstrings in the Python code in
the `sweetpea/` directory. To modify the automatic documentation, you need only
modify the comments in the source code. Currently, we recommend starting with
the in-code documentation of the
[`sweetpea/primitives.py`](https://github.com/pdarragh/sweetpea-py/blob/master/sweetpea/primitives.py)
file.


Style Guides
------------

We have style guides for both :ref:`reST <rest_style_guide>` and :ref:`Python
<py_style_guide>`.