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 Configuring Your 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
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.