deploy: 3f7684c

2.4.0/.buildinfo

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

2.4.0/_sources/explanations.md.txt

@@ -0,0 +1,10 @@
+# Explanations
+
+Explanations of how it works and why it works that way.
+
+```{toctree}
+:maxdepth: 1
+:glob:
+
+explanations/*
+```

2.4.0/_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).

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

@@ -0,0 +1,18 @@
+# 1. Record architecture decisions
+
+## 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.

2.4.0/_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

2.4.0/_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.

2.4.0/_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/

2.4.0/_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.

2.4.0/_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.

2.4.0/_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]
+` ``