Update documentation build action (#226)

- Use towncrier to insert a running changelog of unreleased features
- Publish `docs/_build` directory as an artifact for inspection
- Hopefully fix the towncrier "cannot import project issue"
- Document the documentation build action

Closes #209

.github/workflows/docs-release.yml

@@ -1,24 +1,31 @@
 name: Docs Build
 on:
+  # <trigger-push>
   push:
     branches:
     - develop
     paths:
     - 'arlunio/**'
     - 'docs/**'
     - '.github/workflows/docs-release.yml'
+  # </trigger-push>
+  # <trigger-pr>
   pull_request:
     branches:
     - develop
     paths:
     - 'arlunio/**'
     - 'docs/**'
     - '.github/workflows/docs-release.yml'
+  # </trigger-pr>
 jobs:
+  # <build-job>
   Build:
     runs-on: ubuntu-latest
+  # </build-job>
     steps:
 
+    # <build-job-setup>
     - uses: actions/checkout@v1
     - name: Setup Python
       uses: actions/setup-python@v1
@@ -32,12 +39,31 @@ jobs:
         python -m pip install --upgrade pip
         python -m pip install -e .[doc]
         python -m pip install -r docs/requirements.txt
+    # </build-job-setup>
 
+    # <build-job-docs>
     - 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
+    # </build-job-docs>
+
+    # <build-job-artifact>
+    - name: Publish Artifact
+      uses: actions/upload-artifact@v1.0.0
+      with:
+          name: 'docs'
+          path: docs/_build
+    # </build-job-artifact>
 
+    # <build-job-deploy>
     - name: Deploy
       uses: JamesIves/github-pages-deploy-action@releases/v3
       with:
@@ -46,4 +72,5 @@ jobs:
         BRANCH: gh-pages
         FOLDER: docs/_build/html
         TARGET_FOLDER: docs/
-      if: github.event_name != 'pull_request'
+      if: github.event_name != 'pull_request'
+    # </build-job-deploy>

CHANGES.rst

@@ -1,8 +1,8 @@
 v0.0.6 - 2020-04-18
-===================
+-------------------
 
 Features
---------
+^^^^^^^^
 
 - Introduce the concept of operators. Operators are definitions that can provide
   implementations of the arithmetic operators in Python like :code:`+` and
@@ -15,7 +15,7 @@ Features
 
 
 Docs
-----
+^^^^
 
 - Added some documentation around the CI build for the blog. Also updated the blog
   build to run every day. (`#177 <https://github.com/swyddfa/arlunio/issues/177>`_)
@@ -25,7 +25,7 @@ Docs
 
 
 Misc
-----
+^^^^
 
 - Fix handling of multiple notebooks in  :code:`clean-notebook.sh` and add VSCode
   tasks to aid with tutorial development (`#205 <https://github.com/swyddfa/arlunio/issues/205>`_)

blog/gallery.py

@@ -170,7 +170,6 @@ def find_image(candidates: Dict[str, arlunio.Image]) -> arlunio.Image:
     The process for discovering images is as follows:
 
     - If there is only a single image in the namespace then we'll use that.
-
     - If there is more than one image in the namespace, but there is one called
       'image' then we'll use that.
     """

docs/conf.py

@@ -12,16 +12,26 @@
 #
 import os
 
-import arlunio
-
 # -- Project information -----------------------------------------------------
 
 project = "Arlunio"
 copyright = "2017-, Swyddfa Developers"
 author = "Swyddfa Developers"
 
 # The full version, including alpha/beta/rc tags
-version = arlunio.__version__
+version = None
+
+if "VERSION" in os.environ:
+    version = os.environ["VERSION"]
+
+if version is None:
+    try:
+        import arlunio
+
+        version = arlunio.__version__
+    except Exception:
+        version = "latest"
+
 release = version
 
 

docs/contributing/ci/blog-release.rst

@@ -7,7 +7,7 @@ arlunio website. Currently this is only composed of the gallery.
 Triggers
 --------
 
-This action is triggered when ever a commit has been made to the :code:`develop`
+This action is triggered whenever a commit has been made to the :code:`develop`
 branch within the :code:`blog/` directory so that new additions are published
 immediately.
 
@@ -82,7 +82,7 @@ Delpoy Blog
 ^^^^^^^^^^^
 
 Finally, if this is not a PR build, we publish the built site to our
-:code:`gh-pages` branch using the `JamesIves/github-pages-deploy-action`_.
+:code:`gh-pages` branch using `JamesIves/github-pages-deploy-action`_.
 
 .. literalinclude:: ../../../.github/workflows/blog-release.yml
    :language: yaml

docs/contributing/ci/docs-release.rst

@@ -0,0 +1,103 @@
+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 :code:`develop`
+branch within the :code:`docs/` or :code:`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.
+
+.. literalinclude:: ../../../.github/workflows/docs-release.yml
+   :language: yaml
+   :dedent: 2
+   :start-after: # <trigger-push>
+   :end-before: # </trigger-push>
+
+It's also configured to run on any pull request that affects the paths relevant
+to ensure that changes do not break the build.
+
+.. literalinclude:: ../../../.github/workflows/docs-release.yml
+   :language: yaml
+   :dedent: 2
+   :start-after: # <trigger-pr>
+   :end-before: # </trigger-pr>
+
+
+Jobs
+----
+
+.. literalinclude:: ../../../.github/workflows/docs-release.yml
+   :language: yaml
+   :dedent: 2
+   :start-after: # <build-job>
+   :end-before: # </build-job>
+
+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 :code:`docs/requirements.txt` we also
+need to install :code:`arlunio` itself since it's used to build some aspects of
+the documentation.
+
+.. literalinclude:: ../../../.github/workflows/docs-release.yml
+   :language: yaml
+   :dedent: 4
+   :start-after: # <build-job-setup>
+   :end-before: # </build-job-setup>
+
+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
+
+.. literalinclude:: ../../../.github/workflows/docs-release.yml
+   :language: yaml
+   :dedent: 4
+   :start-after: # <build-job-docs>
+   :end-before: # </build-job-docs>
+
+Publish Build Artifact
+^^^^^^^^^^^^^^^^^^^^^^
+
+So that it's easy to inspect the final build of the documentation if required we
+also publish the :code:`docs/_build` directory as a build artifact.
+
+.. literalinclude:: ../../../.github/workflows/docs-release.yml
+   :language: yaml
+   :dedent: 4
+   :start-after: # <build-job-artifact>
+   :end-before: # </build-job-artifact>
+
+
+Deploy Docs
+^^^^^^^^^^^
+
+Finally assuming the docs have been built successfully and this is not a PR
+build, we deploy the result to Github Pages using
+`JamesIves/github-pages-deploy-action`_.
+
+.. literalinclude:: ../../../.github/workflows/docs-release.yml
+   :language: yaml
+   :dedent: 4
+   :start-after: # <build-job-deploy>
+   :end-before: # </build-job-deploy>
+
+
+.. _JamesIves/github-pages-deploy-action: https://github.com/JamesIves/github-pages-deploy-action

docs/contributing/ci/index.rst

@@ -9,6 +9,7 @@ the actions that are defined and how they work.
    :maxdepth: 1
 
    blog-release
+   docs-release
    python-linting
    python-pr-builds
    python-release

docs/requirements.txt

@@ -1,2 +1,3 @@
 sphinx>=2.0.0
-sphinx_rtd_theme
+sphinx_rtd_theme
+towncrier

pyproject.toml

@@ -24,11 +24,11 @@ lines_between_types = 1
 multi_line_output = 3
 
 [tool.towncrier]
-package = "arlunio"
 filename = "CHANGES.rst"
 directory = "changes/"
 title_format = "{version} - {project_date}"
 issue_format = "`#{issue} <https://github.com/swyddfa/arlunio/issues/{issue}>`_"
+underlines = ["-", "^", "\""]
 
 
 [[tool.towncrier.type]]