deploy: b91597e

main/.buildinfo

@@ -1,4 +1,4 @@
 # Sphinx build info version 1
 # This file hashes the configuration used when building these files. When it is not found, a full rebuild will be done.
-config: b7b03ce0f5c3a708048a495f3e695ebd
+config: aaa89cc1f23ce1e26bdd112860687016
 tags: 645f666f9bcd5a90fca523b33c5a78b7

main/_sources/explanations/decisions.md.txt

@@ -0,0 +1,12 @@
+# Architectural Decision Records
+
+Architectural decisions are made throughout a project's lifetime. As a way of keeping track of these decisions, we record these decisions in Architecture Decision Records (ADRs) listed below.
+
+```{toctree}
+:glob: true
+:maxdepth: 1
+
+decisions/*
+```
+
+For more information on ADRs see this [blog by Michael Nygard](http://thinkrelevance.com/blog/2011/11/15/documenting-architecture-decisions).

main/_sources/explanations/decisions/0001-record-architecture-decisions.md.txt

@@ -0,0 +1,20 @@
+# 1. Record architecture decisions
+
+Date: 2022-02-18
+
+## Status
+
+Accepted
+
+## Context
+
+We need to record the architectural decisions made on this project.
+
+## Decision
+
+We will use Architecture Decision Records, as [described by Michael Nygard](http://thinkrelevance.com/blog/2011/11/15/documenting-architecture-decisions).
+
+## Consequences
+
+See Michael Nygard's article, linked above. To create new ADRs we will copy and
+paste from existing ones.

main/_sources/explanations/decisions/0002-make-skeleton.md.txt

@@ -0,0 +1,21 @@
+# 2. Make a skeleton repository
+
+Date: 2022-06-18
+
+## Status
+
+Accepted
+
+## Context
+
+Many projects start from some kind of template. These define some basic structure, customized with project specific variables, that developers can add their code into. One example of this is [cookiecutter](https://cookiecutter.readthedocs.io).
+
+The problem with this approach is that it is difficult to apply changes to the template into projects that have been cut from it. Individual changes have to be copy/pasted into the code, leading to partially applied fixes and missed updates.
+
+## Decision
+
+We will use a skeleton structure as defined in [Jaraco's blog](https://blog.jaraco.com/a-project-skeleton-for-python-projects/), using git to keep the downstream projects up to date.
+
+## Consequences
+
+We will need a cli module to ease the adoption of this

main/_sources/explanations/decisions/0003-docs-structure.md.txt

@@ -0,0 +1,37 @@
+(documentation-structure)=
+
+# 3. Standard documentation structure
+
+Date: 2023-01-18
+
+## Status
+
+Accepted
+
+## Context
+
+Skeleton based project's documentation requires organizing.
+
+## Decision
+
+Use the approach proposed by David Laing.
+
+> {material-regular}`format_quote;2em`
+>
+> The Grand Unified Theory of Documentation
+>
+> <p class="attribution">-David Laing</p>
+
+There is a secret that needs to be understood in order to write good software
+documentation: there isn't one thing called *documentation*, there are four.
+
+They are: *tutorials*, *how-to guides*, *technical reference* and *explanation*.
+They represent four different purposes or functions, and require four different
+approaches to their creation. Understanding the implications of this will help
+improve most documentation - often immensely.
+
+[More information on this topic.](https://documentation.divio.com)
+
+## Consequences
+
+See article linked above.

main/_sources/explanations/decisions/0004-why-src.md.txt

@@ -0,0 +1,43 @@
+(src)=
+
+# 4. Use a source directory
+
+Date: 2023-01-18
+
+## Status
+
+Accepted
+
+## Context
+
+We need to decide how to structure the source code in skeleton based projects.
+
+## Decision
+
+As per [Hynek's article] and summarized below.
+
+The main advantage is that the source directory cannot shadow installed packages
+as it would if it was in the root of the repository. This means that if you
+install the package, then run the tests, they will run against the installed
+package and not the source directory, testing for packaging bugs.
+
+A secondary advantage is symmetry, sources go in `src/`, tests go in
+`tests\`, docs go in `docs`.
+
+This is tested in CI in the following way:
+
+- `wheel` job creates a wheel, then installs it in an isolated environment and
+  runs the cli. This checks `install_requirements` are sufficient to run the
+  cli.
+- `test` job with `lock: true` does an [editable install] of the
+  package. This is the mode that is used at development time, as modifications
+  to sources can be tested without reinstalling.
+- `test` job with `lock: false` does a regular install, which
+  checks that all files needed for the tests are packaged with the distribution.
+
+## Consequences
+
+See the article linked above.
+
+[editable install]: https://pip.pypa.io/en/stable/cli/pip_install/#editable-installs
+[hynek's article]: https://hynek.me/articles/testing-packaging/

main/_sources/explanations/decisions/0005-pyproject-toml.md.txt

@@ -0,0 +1,19 @@
+# 5. Use pyproject.toml
+
+Date: 2023-01-18
+
+## Status
+
+Accepted
+
+## Context
+
+Need a decision on where to put the python project configuration.
+
+## Decision
+
+Use pyproject.toml as per <https://peps.python.org/pep-0518/>
+
+## Consequences
+
+See article linked above.

main/_sources/explanations/decisions/0006-setuptools-scm.md.txt

@@ -0,0 +1,23 @@
+# 6. Use setuptools_scm
+
+Date: 2023-01-18
+
+## Status
+
+Accepted
+
+## Context
+
+We require a mechanism for generating version numbers in python.
+
+## Decision
+
+Generate the version number from git tags using setuptools scm.
+
+See <https://github.com/pypa/setuptools_scm/>
+
+## Consequences
+
+Versions are generated automatically from git tags. This means you can
+can verify if you are running a released version of the code as
+setup tools scm adds a suffix to untagged commits.

main/_sources/explanations/decisions/0007-dev-dependencies.md.txt

@@ -0,0 +1,32 @@
+# 7. Installing developer environment
+
+Date: 2023-01-18
+
+## Status
+
+Accepted
+
+## Context
+
+We need to provide a way to setup a developer environment for a skeleton based
+project.
+
+## Decision
+
+Use optional dependencies in pyproject.toml.
+
+PEP 621 provides a mechanism for adding optional dependencies in pyproject.toml
+<https://peps.python.org/pep-0621/#dependencies-optional-dependencies>.
+
+We supply a list of developer dependencies under the title "dev". These
+developer dependencies enable building and testing the project and
+its documentation.
+
+## Consequences
+
+Any developer can update their virtual environment in order to work on
+a skeleton based project with the command:
+
+`` `bash
+pip install -e .[dev]
+` ``

main/_sources/explanations/decisions/0008-use-tox.md.txt

@@ -0,0 +1,140 @@
+# 8. Use tox and pre-commit
+
+Date: 2023-01-18
+
+## Status
+
+Accepted
+
+## Context
+
+We require an easy way to locally run the same checks as CI. This provides a
+rapid inner-loop developer experience.
+
+## Decision
+
+Use tox and pre-commit.
+
+tox is an automation tool that we use to run all checks in parallel,
+see <https://tox.wiki/en/latest/>.
+
+pre-commit provides a hook into git commit which runs some of the checks
+against the changes you are about to commit.
+
+## Decision detail
+
+There are a number of things that CI needs to run:
+
+- pytest
+- black
+- mypy
+- flake8
+- isort
+- build documentation
+
+The initial approach this module took was to integrate everything
+under pytest that had a plugin, and isort under flake8:
+
+```{eval-rst}
+.. digraph:: initial
+
+    bgcolor=transparent
+    graph [fontname="Lato" fontsize=10 style=filled fillcolor="#8BC4E9"]
+    node [fontname="Lato" fontsize=10 shape=box style=filled fillcolor="#8BC4E9"]
+
+    subgraph cluster_0 {
+      label = "pytest"
+      "pytest-black"
+      "pytest-mypy"
+      subgraph cluster_1 {
+        label = "pytest-flake8"
+        "flake8-isort"
+      }
+    }
+```
+
+This had the advantage that a `pytest tests` run in CI would catch and
+report all test failures, but made each run take longer than it needed to. Also,
+flake8 states that it [does not have a public, stable, Python API](https://flake8.pycqa.org/en/latest/user/python-api.html) so did not
+recommend the approach taken by pytest-flake8.
+
+To address this, the tree was rearranged:
+
+```{eval-rst}
+.. digraph:: rearranged
+
+    bgcolor=transparent
+    graph [fontname="Lato" fontsize=10 style=filled fillcolor="#8BC4E9"]
+    node [fontname="Lato" fontsize=10 shape=box style=filled fillcolor="#8BC4E9"]
+
+    pytest
+    black
+    mypy
+    subgraph cluster_1 {
+      label = "flake8"
+      "flake8-isort"
+    }
+```
+
+If using VSCode, this will still run black, flake8 and mypy on file save, but
+for those using other editors and for CI another solution was needed. Enter
+[pre-commit](https://pre-commit.com/). This allows hooks to be run at `git
+commit` time on just the files that have changed, as well as on all tracked
+files by CI. All that is needed is a one time install of the git commit hook:
+
+```
+$ pre-commit install
+```
+
+Finally tox was added to run all of the CI checks including
+the documentation build. mypy was moved out of the pre-commit and into tox
+because it was quite long running and
+therefore intrusive. tox can be invoked to run all the checks in
+parallel with:
+
+```
+$ tox -p
+```
+
+The graph now looks like:
+
+```{eval-rst}
+.. digraph:: rearranged
+
+    bgcolor=transparent
+    graph [fontname="Lato" fontsize=10 style=filled fillcolor="#8BC4E9"]
+    node [fontname="Lato" fontsize=10 shape=box style=filled fillcolor="#8BC4E9"]
+
+    subgraph cluster_0
+    {
+        label = "tox -p"
+        pytest
+        mypy
+        "sphinx-build"
+        subgraph cluster_1 {
+            label = "pre-commit"
+            black
+            subgraph cluster_2 {
+                label = "flake8"
+                "flake8-isort"
+            }
+        }
+    }
+```
+
+Now the workflow looks like this:
+
+- Save file, VSCode runs black, flake8 and mypy on it
+- Run 'tox -p' and fix issues until it succeeds
+- Commit files and pre-commit runs black and flake8 on them (if the
+  developer had not run tox then this catches some of the most common issues)
+- Push to remote and CI runs black, flake8, mypy once on all files
+  (using tox), then pytest multiple times in a test matrix
+
+## Consequences
+
+Running `tox -p` before pushing to GitHub verifies that the CI will *most
+likely* succeed.
+
+Committing changes to git will run all of the non-time critical checks and
+help avoid some of the most common mistakes.

main/_sources/explanations/decisions/0009-sphinx-theme.md.txt

@@ -0,0 +1,19 @@
+# 9. Sphinx theme
+
+Date: 2023-01-18
+
+## Status
+
+Accepted
+
+## Context
+
+Documentation requires a theme as well as a structure.
+
+## Decision
+
+Use the pydata theme defined here <https://pydata-sphinx-theme.readthedocs.io/>
+
+## Consequences
+
+The documentation looks nice and has good navigation features.