Publishing documentation

If your source_url is on GitHub, you can automatically deploy your documentation to your repository’s GitHub Pages site. This deployment is controlled by the deploy_docs setting.

Setup

To enable documentation publishing, follow these steps:

  1. On GitHub, navigate to your repository and click on Settings.

  2. Select Pages.

  3. Under Build and deployment source, ensure GitHub Actions is selected.

  4. Select Environments.

  5. Click on github-pages.

  6. Under Deployment branches and tags, click on Add deployment branch or tag rule

  7. Ensure Ref type is Branch (the default).

  8. As the Name pattern, enter main (docs deployments always run from the default branch – release deployments are part of the workflow_run-triggered release finalization).

  9. Click on Add rule.

Once configured, your documentation is automatically published to your GitHub Pages site when publishing a release or after pushes to the default branch (if deploy_docs == rolling).

Further steps

Docs URL in metadata

Ensure the docs_url points to your GitHub Pages site. This URL is included in the project’s PyPI metadata and ensures that the README.md contains a link to the user documentation.

Repository website

Consider setting your GitHub Pages site as the project’s website on GitHub:

  1. In your repository, click the settings wheel in the top right corner (not the Settings tab in the navigation bar).

  2. Under Website, select Use your GitHub Pages website.