Add some more ADRs

docs/explanations/decisions.md

@@ -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).

docs/explanations/decisions/0001-record-architecture-decisions.md

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

docs/explanations/decisions/0002-make-skeleton.md

@@ -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

docs/explanations/decisions/0003-docs-structure.rst → docs/explanations/decisions/0003-docs-structure.md

@@ -1,30 +1,26 @@
-.. _documentation-structure:
+(documentation-structure)=
 
-3. Standard documentation structure
-===================================
+# 3. Standard documentation structure
 
 Date: 2023-01-18
 
-Status
-------
+## Status
 
 Accepted
 
-Context
--------
+## Context
 
 Skeleton based project's documentation requires organizing.
 
-Decision
---------
+## Decision
 
 Use the approach proposed by David Laing.
 
-  :material-regular:`format_quote;2em`
-
-  The Grand Unified Theory of Documentation
-
-  -- 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.
@@ -34,9 +30,8 @@ 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>`_
+[More information on this topic.](https://documentation.divio.com)
 
-Consequences
-------------
+## Consequences
 
 See article linked above.

docs/explanations/decisions/0004-why-src.md

@@ -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/

docs/explanations/decisions/0005-pyproject-toml.md

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

docs/explanations/decisions/0006-setuptools-scm.rst → docs/explanations/decisions/0006-setuptools-scm.md

@@ -1,27 +1,22 @@
-6. Use setuptools_scm
-=====================
+# 6. Use setuptools_scm
 
 Date: 2023-01-18
 
-Status
-------
+## Status
 
 Accepted
 
-Context
--------
+## Context
 
 We require a mechanism for generating version numbers in python.
 
-Decision
---------
+## Decision
 
 Generate the version number from git tags using setuptools scm.
 
-See https://github.com/pypa/setuptools_scm/
+See <https://github.com/pypa/setuptools_scm/>
 
-Consequences
-------------
+## 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

docs/explanations/decisions/0007-dev-dependencies.rst → docs/explanations/decisions/0007-dev-dependencies.md

@@ -1,37 +1,32 @@
-7. Installing developer environment
-===================================
+# 7. Installing developer environment
 
 Date: 2023-01-18
 
-Status
-------
+## Status
 
 Accepted
 
-Context
--------
+## Context
 
 We need to provide a way to setup a developer environment for a skeleton based
 project.
 
-Decision
---------
+## 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.
+<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
-------------
+## Consequences
 
 Any developer can update their virtual environment in order to work on
 a skeleton based project with the command:
 
-```bash
+`` `bash
 pip install -e .[dev]
-```
+` ``