Using github actions to publish documentation

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-latest
  container:
    image: python:3.6
    volumes:
      - dist:dist
      - public:public
  steps:

    # 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@v1
      with:
        name: distributions
        path: 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: Building documentation
      run: |
        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: github pages deploy
      uses: peaceiris/[email protected]
      env:
        PERSONAL_TOKEN: ${{ secrets.PAT }}
        PUBLISH_BRANCH: gh-pages
        PUBLISH_DIR: public

    # since gh-pages has a history, this step might no longer be necessary.
    - uses: actions/upload-artifact@v1
      with:
        name: documentation
        path: public

---

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

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: github pages

on:
  push:
    branches:
      - main

jobs:
  deploy:
    runs-on: ubuntu-18.04
    steps:
      - uses: actions/checkout@v2

      - name: Setup Python
        uses: actions/setup-python@v2
        with:
          python-version: '3.8'

      - name: Upgrade pip
        run: |
          # install pip=>20.1 to use "pip cache dir"
          python3 -m pip install --upgrade pip

      - name: Get pip cache dir
        id: pip-cache
        run: echo "::set-output name=dir::$(pip cache dir)"

      - name: Cache dependencies
        uses: actions/cache@v2
        with:
          path: ${{ steps.pip-cache.outputs.dir }}
          key: ${{ runner.os }}-pip-${{ hashFiles('**/requirements.txt') }}
          restore-keys: |
            ${{ runner.os }}-pip-

      - name: Install dependencies
        run: python3 -m pip install -r ./requirements.txt

      - run: mkdocs build

      - name: Deploy
        uses: peaceiris/actions-gh-pages@v3
        with:
          github_token: ${{ secrets.GITHUB_TOKEN }}
          publish_dir: ./site