deploy: 7fa46bc

1.0.2/.buildinfo

@@ -0,0 +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: 8d67960f4a8fa96f02d11bcebcfb0f7c
+tags: 645f666f9bcd5a90fca523b33c5a78b7

1.0.2/_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/*
+```

1.0.2/_sources/explanations/decisions.rst.txt

@@ -0,0 +1,17 @@
+.. This Source Code Form is subject to the terms of the Mozilla Public
+.. License, v. 2.0. If a copy of the MPL was not distributed with this
+.. file, You can obtain one at http://mozilla.org/MPL/2.0/.
+
+Architectural Decision Records
+==============================
+
+We record major architectural decisions in Architecture Decision Records (ADRs),
+as `described by Michael Nygard
+<http://thinkrelevance.com/blog/2011/11/15/documenting-architecture-decisions>`_.
+Below is the list of our current ADRs.
+
+.. toctree::
+    :maxdepth: 1
+    :glob:
+
+    decisions/*

1.0.2/_sources/explanations/decisions/0001-record-architecture-decisions.rst.txt

@@ -0,0 +1,24 @@
+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.

1.0.2/_sources/explanations/decisions/0003-docs-structure.rst.txt

@@ -0,0 +1,42 @@
+.. _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
+
+  -- David Laing
+
+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.

1.0.2/_sources/explanations/decisions/0004-why-src.rst.txt

@@ -0,0 +1,50 @@
+.. _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.
+
+.. _Hynek's article: https://hynek.me/articles/testing-packaging/
+
+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.
+
+.. _editable install: https://pip.pypa.io/en/stable/cli/pip_install/#editable-installs
+
+Consequences
+------------
+
+See the article linked above.

1.0.2/_sources/explanations/decisions/0005-pyproject-toml.rst.txt

@@ -0,0 +1,25 @@
+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.

1.0.2/_sources/explanations/decisions/0006-setuptools-scm.rst.txt

@@ -0,0 +1,28 @@
+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.

1.0.2/_sources/explanations/decisions/0007-dev-dependencies.rst.txt

@@ -0,0 +1,37 @@
+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]
+```