Deploying documentation

The PTB uses ref:sphinx to build and validate the contents of your project’s documentation. PTB expects the project’s documentation in directory doc, primarily as rst files. The doc/conf.py acts as the configuration file for building the documentation.

GitHub workflow checks.yml also runs the checks for the documentation. This enables updating and fixing the documentation together with other changes in the same pull request. The final building & serving of the documentation happens in GitHub workflow gh-pages.yml.

Nox session

CI Usage

Action

docs:build

checks.yml

Builds the documentation

docs:clean

No

Removes the documentation build folder

docs:multiversion

gh-pages.yml

Builds the multiversion documentation

docs:open

No

Opens the built documentation

links:check

checks.yml

Checks if all links in the documentation are accessible

links:list

No

Lists all links in the documentation

Configuration

doc/conf.py

The PTB’s cookiecutter project template already provides a file doc/conf.py with default content. If your project needs adjustment, please refer to:

gh-pages.yml

GitHub workflow gh-pages.yml uses actions upload-pages-artifact and deploy-pages. In order to properly deploy your generated documentation, you will need to manually reconfigure the GitHub Pages settings for the repo:

  1. Go to the affected repo’s GitHub page

  2. Select ‘Settings’

  3. Scroll down & select ‘Pages’

  4. Within the ‘Build and deployment’ section, change ‘Source’ to ‘GitHub Actions’.

You also need to configure settings for the github-pages environment:

  1. Go to the affected repo’s GitHub page

  2. Select ‘Settings’

  3. Scroll down & select ‘Environment’

  4. Click on ‘github-pages’

  5. In the ‘Deployment branches and tags’, click ‘Add deployment branch or tag rule’

  6. Select ‘Ref type’ to be ‘Tag’ and set the ‘Name pattern’ to [0-9]*.[0-9]*.[0-9]* (or whatever matches that repo’s tags)