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:

  1. The repository settings on Read the docs instruct pull requests to be built.

  2. The correct web hook is in place on Github.

  3. 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:

../../../_images/main.png

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:

../../../_images/main1.png

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:

../../../_images/main2.png ../../../_images/main3.png

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:

../../../_images/main4.png

For example here is how the documentation looked for pull request that added this specific page of the documentation:

../../../_images/main5.png