Hosting documentation on Read The Docs¶
Read the docs is a web service that builds and hosts documentation. You can read more about the service here: https://readthedocs.org
The documentation contained in docs/
is automatically built and can be
viewed at https://nashpy.readthedocs.io/en/stable/.
Versions¶
The default version (ie when going to https://nashpy.readthedocs.io/) is the
stable
version which means the last release.
You can view the version of the documentation currently on the main
branch by going to: https://nashpy.readthedocs.io/latest.
Configuration file¶
Read the docs can have specific settings set in a .readthedocs.yml
file.
Details on this can be found here:
https://docs.readthedocs.io/en/stable/config-file/v2.html#packages
One specific setting used by Nashpy is:
python:
version: 3.8
install:
- method: pip
path: .
extra_requirements:
- doc
This ensures Read the docs does not look for a requirements.txt
file to
install the library. Instead it runs pip install .
which uses
The pyproject.toml file. It also uses the extra requirements specified by
[doc]
in the pyproject.toml
file.
A powerful feature offered by Read the docs is that it can build documentation in pull requests.
Building documentation in pull requests¶
To set this up you need to ensure the following things are done:
The repository settings on Read the docs instruct pull requests to be built.
The correct web hook is in place on Github.
The correct settings of the web hook are done on the Github repository.
To instruct pull requests to be built ensure the following box is ticked in the Advanced settings for your project on Read the docs:
Setting up the web hooks correctly is described here: https://docs.readthedocs.io/en/latest/pull-requests.html
When done correctly this is what Applications settings should look like:
The final thing to check is the setting on the specific Github repository (under
Settings/Webhooks
) which
should have the following 4 boxes ticked:
Branch or tag creation
Branch or tag deletion
Pull requests
Pushes
When done correctly this should look like:
This is described here: https://docs.readthedocs.io/en/latest/webhooks.html#github (although note that ticking the Pull Requests box is not indicated there).
Reviewing documentation on Pull Requests¶
If this is all done correctly you will be able to view your documentation during pull requests:
For example here is how the documentation looked for pull request that added this specific page of the documentation: