diff --git a/.github/workflows/docs-release.yml b/.github/workflows/docs-release.yml
index 450b6795..dd439461 100644
--- a/.github/workflows/docs-release.yml
+++ b/.github/workflows/docs-release.yml
@@ -1,5 +1,6 @@
name: Docs Build
on:
+ #
push:
branches:
- develop
@@ -7,6 +8,8 @@ on:
- 'arlunio/**'
- 'docs/**'
- '.github/workflows/docs-release.yml'
+ #
+ #
pull_request:
branches:
- develop
@@ -14,11 +17,15 @@ on:
- 'arlunio/**'
- 'docs/**'
- '.github/workflows/docs-release.yml'
+ #
jobs:
+ #
Build:
runs-on: ubuntu-latest
+ #
steps:
+ #
- 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
+ #
+ #
- 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
+ #
+
+ #
+ - name: Publish Artifact
+ uses: actions/upload-artifact@v1.0.0
+ with:
+ name: 'docs'
+ path: docs/_build
+ #
+ #
- 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'
\ No newline at end of file
+ if: github.event_name != 'pull_request'
+ #
diff --git a/CHANGES.rst b/CHANGES.rst
index b0824585..da415401 100644
--- a/CHANGES.rst
+++ b/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 `_)
@@ -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 `_)
diff --git a/blog/gallery.py b/blog/gallery.py
index 0cad1a87..dd4bf0ad 100644
--- a/blog/gallery.py
+++ b/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.
"""
diff --git a/docs/conf.py b/docs/conf.py
index 724c23d9..003662d7 100644
--- a/docs/conf.py
+++ b/docs/conf.py
@@ -12,8 +12,6 @@
#
import os
-import arlunio
-
# -- Project information -----------------------------------------------------
project = "Arlunio"
@@ -21,7 +19,19 @@
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
diff --git a/docs/contributing/ci/blog-release.rst b/docs/contributing/ci/blog-release.rst
index 5c53e196..afd20b3e 100644
--- a/docs/contributing/ci/blog-release.rst
+++ b/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
diff --git a/docs/contributing/ci/docs-release.rst b/docs/contributing/ci/docs-release.rst
new file mode 100644
index 00000000..e9d19d0a
--- /dev/null
+++ b/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: #
+ :end-before: #
+
+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: #
+ :end-before: #
+
+
+Jobs
+----
+
+.. literalinclude:: ../../../.github/workflows/docs-release.yml
+ :language: yaml
+ :dedent: 2
+ :start-after: #
+ :end-before: #
+
+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: #
+ :end-before: #
+
+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: #
+ :end-before: #
+
+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: #
+ :end-before: #
+
+
+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: #
+ :end-before: #
+
+
+.. _JamesIves/github-pages-deploy-action: https://github.com/JamesIves/github-pages-deploy-action
diff --git a/docs/contributing/ci/index.rst b/docs/contributing/ci/index.rst
index 0ad0394a..df3d0eab 100644
--- a/docs/contributing/ci/index.rst
+++ b/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
diff --git a/docs/requirements.txt b/docs/requirements.txt
index f07244de..c98fb6af 100644
--- a/docs/requirements.txt
+++ b/docs/requirements.txt
@@ -1,2 +1,3 @@
sphinx>=2.0.0
-sphinx_rtd_theme
\ No newline at end of file
+sphinx_rtd_theme
+towncrier
diff --git a/pyproject.toml b/pyproject.toml
index be6e10f0..42a09e15 100644
--- a/pyproject.toml
+++ b/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} `_"
+underlines = ["-", "^", "\""]
[[tool.towncrier.type]]