Using Github Actions To Publish Documentation

What I considered: github offers github pages to host documentation in either a folder on my master branch or a dedicated gh-pages branch, but that would mean to commit build arti

Solution 1:

In the case of managing sphinx using pip (requirements.txt), pipenv, or poetry, we can deploy our documentation to GitHub Pages as follows. For also other Python-based Static Site Generators like pelican and MkDocs, the workflow works as same. Here is a simple example of MkDocs. We just add the workflow as .github/workflows/gh-pages.yml

For more options, see the latest README: peaceiris/actions-gh-pages: GitHub Actions for GitHub Pages 🚀 Deploy static files and publish your site easily. Static-Site-Generators-friendly.

name:githubpageson:push:branches:-mainjobs:deploy:runs-on:ubuntu-18.04steps:-uses:actions/checkout@v2-name:SetupPythonuses:actions/setup-python@v2with:python-version:'3.8'-name:Upgradepiprun:|
          # install pip=>20.1 to use "pip cache dir"
          python3 -m pip install --upgrade pip
-name:Getpipcachedirid:pip-cacherun:echo"::set-output name=dir::$(pip cache dir)"-name:Cachedependenciesuses:actions/cache@v2with:path:${{steps.pip-cache.outputs.dir}}key:${{runner.os}}-pip-${{hashFiles('**/requirements.txt')}}restore-keys:|
            ${{ runner.os }}-pip-
-name:Installdependenciesrun:python3-mpipinstall-r./requirements.txt-run:mkdocsbuild-name:Deployuses:peaceiris/actions-gh-pages@v3with:github_token:${{secrets.GITHUB_TOKEN}}publish_dir:./site

Solution 2:

I got it to work, but there is no dedicated action to build and host sphinx docs on either github pages or readthedocs as of yet, so as far as I am concerned there is quite a bit left to be desired here.

This is my current release_sphinx job that uses the deploy-action-for-github-pages action and uploads to github-pages:

release_sphinx:needs: [build]
  runs-on:ubuntu-latestcontainer:image:python:3.6volumes:-dist:dist-public:publicsteps:# check out sources that will be used for autodocs, plus readme-uses:actions/checkout@v1# download wheel that was build and uploaded in the build step-uses:actions/download-artifact@v1with:name:distributionspath:dist# didn't need to change anything here, but had to add sphinx.ext.githubpages# to my conf.py extensions list. that fixes the broken uploads-name:Buildingdocumentationrun:|
        pip install dist/*.whl
        pip install sphinx Pallets-Sphinx-Themes
        sphinx-apidoc --no-toc --module-first -o docs/autodoc src/stenotype
        sphinx-build docs public -b dirhtml
# still need to build and set the PAT to get a rebuild on the pages job,# apart from that quite clean and nice -name:githubpagesdeployuses:peaceiris/actions-gh-pages@v2.3.1env:PERSONAL_TOKEN:${{secrets.PAT}}PUBLISH_BRANCH:gh-pagesPUBLISH_DIR:public# since gh-pages has a history, this step might no longer be necessary.-uses:actions/upload-artifact@v1with:name:documentationpath:public

---

Shoutout to the deploy action's maintainer, who resolved the upload problem within 8 minutes of me posting it as an issue.