Project Documentation¶
Every good project has even better documentation! Luckily, it is now very easy to publish documentation for python projects. You can make an account at readthedocs and link a project in your Github to readthedocs.
To publish our documentation, we use Sphinx to generate python documentation. Sphinx automatically builds documentation and can also add automatic API documentation.
We have provided some documentation in the docs/
directory. This directory contains
reStructuredText (rst) files that contain documentation we would like the public to see. Additionally,
there are some other files:
conf.py
: configuration file that is required by Sphinx. Documentation for conf.py can be found here.Makefile
: This is an optional file that makes it easy to build and view your docs locally before pushing them to readthedocs.requirements.txt
: This file contains python requirements needed to build docs locally.
Building documentation locally¶
First, install requirements:
cd docs
pip install -r requirements.txt
Next, you can generate the documentation to view locally:
make html
You can view the documentation locally by opening docs/_build/index.html
in your favorite web browser.
Autogenerating API Documentation¶
Navigate to _build/html/
and open index.html
in your web browser to view docs locally.
Here, you will see the documentation that looks just like these docs. Additionally, you will see API Documentation.
We use Sphinx’s autosummary feature to
automatically generate documentation for our package. This also requires respective file headers in our package files
(functions.py, __init__.py, and PlotMAPQ.py) so autosummary can find and generate the API documentation for the designated functions.
Adding documentation to readthedocs¶
Finally, we want to publish our documentation so it is visible to anyone who wants to use our tool.
- Navigate to readthedocs. If you do not have an account, create one. You will have to link your Github account with your readthedocs account to access your github repositories.
- Click
Import a Project
- Find the project you would like to import. Readthedocs will automatically pull docs from your
docs
directory.
You can view our documentation at readthedocs.