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 release/auto (the branch name used by the automated release PR).

  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.