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 (may differ depending on your Sphinx setup, GitHub repositories setup, etc.):
- Write the documentation using Sphinx
- Make sure that you can build the documentation using
make html
in a virtual environment- 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
- In the settings for your repository, on the left-hand side click on
Pages
and then inSource
, selectDeploy from a branch
. In Branch, selectgh-pages
(or the name that you chose for the branch) and select the folder/docs
You also need to :ref:`setup the destination repository <setup>` to be able to push there.
In the origin repository where the documentation source files (usually *.rst files) are pushed, create a file named .github/workflows/publish.yml
:
name: build documentation and publish
on:
push:
branches: [ main ]
pull_request:
branches: [ main ]
jobs:
publish:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v2
- uses: actions/setup-python@v4
with:
python-version: '3.9'
- run: pip install -r requirements.txt
- name: build documentation
run: make html
- run: touch _build/html/.nojekyll
- uses: cpina/github-action-push-to-another-repository@main
env:
SSH_DEPLOY_KEY: ${{ secrets.SSH_DEPLOY_KEY }}
with:
source-directory: '_build/html'
destination-github-username: 'cpina'
destination-repository-name: 'push-to-another-repository-docs'
user-email: carles@pina.cat
target-branch: gh-pages
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 thetarget-branch
matches the one setup in the repository settings