Sphinx example

Introduction

It is possible to use the github-action-push-to-another-repository to publish Sphinx documentation that is pushed into a GitHub repository, into GitHub Pages (for example, pushing the generated documentation into a branch of the same repository).

The documentation for this Action is published using the documented Action.

In the following example, the documentation is pushed into a repository and the same repository (different branch) is used to make the documentation available using GitHub Pages. This could also be done using a different repository.

Steps

Steps (may differ depending on your Sphinx setup, GitHub repositories setup, etc.):

  1. Write the documentation using Sphinx

  2. Make sure that you can build the documentation using make html in a virtual environment

  3. Using the git command line or even the GitHub page for your repository (clicking on the branches), create a new branch, for example, gh-pages

  4. In the settings for your repository, on the left-hand side click on Pages and then in Source, select Deploy from a branch. In Branch, select gh-pages (or the name that you chose for the branch) and select the folder /docs

You also need to setup the destination repository to be able to push there.

Configuration

In the origin repository where the documentation source files (usually *.rst files) are pushed, create a file named .github/workflows/publish.yml:

 1name: build documentation and publish
 2
 3on:
 4  push:
 5    branches: [ main ]
 6  pull_request:
 7    branches: [ main ]
 8
 9jobs:
10  publish:
11    runs-on: ubuntu-latest
12    steps:
13      - uses: actions/checkout@v2
14      - uses: actions/setup-python@v4
15        with:
16          python-version: '3.9'
17      - run: pip install -r requirements.txt
18      - name: build documentation
19        run: make html
20      - run: touch _build/html/.nojekyll
21      - uses: cpina/github-action-push-to-another-repository@main
22        env:
23          SSH_DEPLOY_KEY: ${{ secrets.SSH_DEPLOY_KEY }}
24        with:
25          source-directory: '_build/html'
26          destination-github-username: 'cpina'
27          destination-repository-name: 'push-to-another-repository-docs'
28          user-email: carles@pina.cat
29          target-branch: gh-pages
30          target-directory: docs

Relevant lines:

  • Checkout the origin repository (line 13)

  • Setup Python version 3.9 (lines 14-16)

  • Install the packages in your requirements.txt (contains Sphinx) (line 17)

  • Build the documentation (line 18-19)

  • Create the .nojekyll file to also publish the _static directory (as documented) (line 20)

  • Follow the usual github-action-push-to-another-repository setup (lines 21-30). The destination-repository-name is the same in which the Action is executed, and the target-branch matches the one setup in the repository settings