Sphinx to GitHub Pages V3¶

https://img.shields.io/github/stars/sphinx-notes/pages.svg?style=social&label=Star&maxAge=2592000

Helps you deploy your Sphinx documentation to Github Pages.

Usage¶

We provides two ways for publishing GitHub pages. The first one is the default but still in beta, use the second one if you tend to be stable.

Publishing with this action (default)¶

Set the publishing sources to “Github Actions”

Create the following workflow:

name: Deploy Sphinx documentation to Pages

on:
  push:
    branches: [master] # branch to trigger deployment

jobs:
  pages:
    runs-on: ubuntu-20.04
    environment:
      name: github-pages
      url: ${{ steps.deployment.outputs.page_url }}
    permissions:
      pages: write
      id-token: write
    steps:
    - id: deployment
      uses: sphinx-notes/pages@v3

Publishing from a branch (classical)¶

Create a branch gh-pages
Set the publishing sources to “Deploy from a branch”, then specify the branch just created

Create the following workflow, in this way user need to publish the site by another action, we use peaceiris/actions-gh-pages here:

name: Deploy Sphinx documentation to Pages

on:
  push:
    branches: [master] # branch to trigger deployment

jobs:
  pages:
    runs-on: ubuntu-20.04
    steps:
    - id: deployment
      uses: sphinx-notes/pages@v3
      with:
        publish: false
    - uses: peaceiris/actions-gh-pages@v3
      with:
        github_token: ${{ secrets.GITHUB_TOKEN }}
        publish_dir: ${{ steps.deployment.outputs.artifact }}

Inputs¶

Input	Default	Required	Description
`documentation_path`	`./docs`	false	Path to Sphinx source files
`requirements_path`	`./docs/requirements.txt`	false	Path to to requirements file, used in `pip install -r XXX` command
`pyproject_extras`	`docs`	false	Extras of Requirement Specifier used in `pip install .[XXX]`

Advanced¶

In most cases you don’t need to know about the following inputs. Unless you need to highly customize the action’s behavior.

Input	Default	Required	Description
`python_version`	`3.10`	false	Version of Python
`sphinx_version`	`latest`	false	Version of Sphinx
`sphinx_build_options`		false	Additional options passed to `sphinx-build`
`cache`	`false`	false	Enable cache to speed up documentation building
`checkout`	`true`	false	Whether to automatically checkout the repository, if false, user need to do it byself
`publish`	`true`	false	Whether to automatically publish the repository

Outputs¶

Output	Description
`page_url`	URL to deployed GitHub Pages, only available when option `publish` is set to `true`
`artifact`	Directory where artifact (HTML documentation) is stored, user can use it to deploy GitHub Pages manually

Examples¶

The following repository’s pages are built by this action:

You can find the workflow file in the above repositories.

Tips¶

Copy extra files to site¶

Use Sphinx confval html_extra_path.

Cancel any in-progress job¶

It is useful when you have pushed a new commit to remote but the job of the previous commit is not finished yet. See concurrency for more details.

concurrency:
  group: ${{ github.ref }}
  cancel-in-progress: true

Install extra dependencies¶

For python dependencies, just add them to your requirements.txt or pyproject.toml file.

For non-python dependencies, add a step to your workflow file, and install them with the appropriate tools (such as apt, wget, …). See #24 for example.

Customize checkout options¶

Repository is automatically checkout by default, but some user may need to customize checkout options (For example, checkout private repository, checkout multiple repositories). For this case, user can set the checkout options to false, then use action/checkout byeself.

steps:
- uses: actions/checkout@master
  with:
    YOUR_CUSTOM_OPTIONS: ...
- id: deployment
  uses: sphinx-notes/pages@v3
  with:
    checkout: false

The Sphinx Notes Project¶

This project is a developed by Shengyu Zhang, as part of The Sphinx Notes Project.

The Sphinx Notes Project