Documentation Release

This action is responsible for building and deploying the documentation which currently sits alongside the gallery in our Github Pages instance.

Triggers

This action is triggered whenever a commit has been made to the develop branch within the docs/ or arlunio/ directories. This means the documentation is updated to always align with the bleeding edge version of the codebase. Since we don’t currently have a stable released version this is sufficient for now, though may need to be revised at some point in the future.

push:
  branches:
  - develop
  paths:
  - 'arlunio/**'
  - 'docs/**'
  - '.github/workflows/docs-release.yml'

It’s also configured to run on any pull request that affects the paths relevant to ensure that changes do not break the build.

pull_request:
  branches:
  - develop
  paths:
  - 'arlunio/**'
  - 'docs/**'
  - '.github/workflows/docs-release.yml'

Jobs

Build:
  runs-on: ubuntu-latest

Steps

Setup

Setup for this job is fairly standard in that we checkout the repository and get ourselves setup with a Python version. The only interesting thing to note is that alongside the dependencies listed in docs/requirements.txt we also need to install arlunio itself since it’s used to build some aspects of the documentation.

- uses: actions/checkout@v1
- name: Setup Python
  uses: actions/setup-python@v1
  with:
    python-version: 3.7

- name: Setup Environment
  run: |
    python --version

    python -m pip install --upgrade pip
    python -m pip install -e .[doc]
    python -m pip install -r docs/requirements.txt

Build Docs

Since the documentation is built using Sphinx it follows standard practice for the most part. However before running the Sphinx build we:

• Use towncrier to update the changelog with details of anything that will be coming up in the next release.

• Fetch the latest release from Github so we can set the appropriate version number in Sphinx

- name: Build Docs
  run: |

    version=$(cat arlunio/_version.py | sed 's/.*"\(.*\)"/\1/')
    towncrier --date 'Unreleased' --version "v${version}" --yes

    latest=$(curl -s "https://api.github.com/repos/swyddfa/arlunio/releases" | jq -r '.[0].tag_name')
    export VERSION="$latest"

    cd docs
    make html
    make nbtutorial

Note that we also run the nbtutorial builder to create a Jupyter compatible version of the tutorial which we can also publish.

Publish Build Artifact

So that it’s easy to inspect the final build of the documentation if required we also publish the docs/_build directory as a build artifact.

- name: Publish Artifact
  uses: actions/upload-artifact@v1.0.0
  with:
      name: 'docs'
      path: docs/_build

Deploy Docs

Finally assuming that the docs have been built successfully and this is not a PR build, we deploy both the HTML documentation as well as the notebook version of the tutorial to Github Pages using JamesIves/github-pages-deploy-action.

- name: Deploy HTML Docs
  uses: JamesIves/github-pages-deploy-action@releases/v3
  with:
    ACCESS_TOKEN: ${{ secrets.ACCESS_TOKEN }}
    BASE_BRANCH: develop
    BRANCH: gh-pages
    FOLDER: docs/_build/html
    TARGET_FOLDER: docs/
  if: github.event_name != 'pull_request'

- name: Deploy Tutorial Notebooks
  uses: JamesIves/github-pages-deploy-action@releases/v3
  with:
    ACCESS_TOKEN: ${{ secrets.ACCESS_TOKEN }}
    BASE_BRANCH: develop
    BRANCH: gh-pages
    FOLDER: docs/_build/nbtutorial/
    TARGET_FOLDER: tutorial/
  if: github.event_name != 'pull_request'