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/.
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
branch by going to: https://nashpy.readthedocs.io/latest.
Read the docs can have specific settings set in a
Details on this can be found here:
One specific setting used by Nashpy is:
- method: pip
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
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
should have the following 4 boxes ticked:
Branch or tag creation
Branch or tag deletion
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: