Using github actions to publish documentation

Question

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 artifacts
• I can also let readthedocs build and host docs for me through webhooks, but that means learning how to configure Yet Another Tool at a point in time where I try to consolidate everything related to my project in github-actions

I already have a docu-building process that works for me (using sphinx as the builder) and that I can also test locally, so I'd rather just leverage that instead. It has all the rules set up and drops some static html in an artifact - it just doesn't get served anywhere. Handling it in the workflow, where all the other deployment configuration of my project is living, feels better than scattering it over different tools or github specific options.

Is there already an action in the marketplace that allows me to do something like this?

name: CI
on: [push]
jobs:
  
  ...  # do stuff like building my-project-v1.2.3.whl, testing, etc.
  
  release_docs:
    steps:
      - uses: actions/sphinx-to-pages@v1  # I wish this existed
        with:
          dependencies:
            - some-sphinx-extension
            - dist/my-project*.whl
          apidoc_args:
            - "--no-toc"
            - "--module-first"
            - "-o docs/autodoc"
            - "src/my-project"
          build-args:
            - "docs"
            - "public"  # the content of this folder will then be served at
                        # https://my_gh_name.github.io/my_project/

In other words, I'd like to still have control over how the build happens and where artifacts are dropped, but do not want to need to handle the interaction with readthedocs or github-pages.

---

###Actions that I tried

❌ deploy-to-github-pages: runs the docs build in an npm container - will be inconvenient to make it work with python and sphinx

❌ gh-pages-for-github-action: no documentation

❌ gh-pages-deploy: seems to target host envs like jekyll instead of static content, and correct usage with yml syntax not yet documented - I tried a little and couldn't get it to work

❌ github-pages-deploy: looks good, but correct usage with yml syntax not yet documented

---

✅ github-pages: needs a custom PAT in order to trigger rebuilds (which is inconvenient) and uploads broken html (which is bad, but might be my fault)

✅ deploy-action-for-github-pages: also works, and looks a little cleaner in the logs. Same limitations as the upper solution though, it needs a PAT and the served html is still broken.

---

The eleven other results when searching for github+pages on the action marketplace all look like they want to use their own builder, which sadly never happens to be sphinx.

Idou

There are a lot of GitHub Pages actions on the marketplace. Do none of these do what you want? github.com/… – Responsibility

I am trying to get this one to work right now, and it would be a reasonable workaround I guess. But as far as I could see all of them don't support just pushing artifacts, they will instead create the docs/ folder in master or push to gh-pages. – Idou

@Responsibility I tested it and it doesn't work for me. I'll update my question with what actions I tried. – Idou

You mention that some of the actions don't support yaml syntax. I don't think that is the case. It's just that the owners haven't updated their examples to show the new way to reference the action in yaml. For one of the actions above, you can see here that someone has raised a PR to update the documentation. github.com/Cecilapp/GitHub-Pages-deploy/pull/3/files – Responsibility

I tried fiddling around with that action in particular, and ended up assuming that there just is no translation between the styles unless written. Thanks for pointing it out, I'll change my comments. – Idou

Answer 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: 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

Sarcenet

ReadTheDocs can host multiple versions of the docs (pretty important for e.g. stable and master): is there any way to do that here? – Temper

Answer 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-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.

Idou