deploy: 4db4c73

153_fix_docs_build/.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: 3ebbfe0c978bfa152941e24688ff87f1
+tags: 645f666f9bcd5a90fca523b33c5a78b7

153_fix_docs_build/_sources/developer/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/*

153_fix_docs_build/_sources/developer/explanations/decisions/0001-record-architecture-decisions.rst.txt

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

153_fix_docs_build/_sources/developer/explanations/decisions/0002-switched-to-pip-skeleton.rst.txt

@@ -0,0 +1,35 @@
+2. Adopt python3-pip-skeleton for project structure
+===================================================
+
+Date: 2022-02-18
+
+Status
+------
+
+Accepted
+
+Context
+-------
+
+We should use the following `pip-skeleton <https://github.com/DiamondLightSource/python3-pip-skeleton>`_.
+The skeleton will ensure consistency in developer
+environments and package management.
+
+Decision
+--------
+
+We have switched to using the skeleton.
+
+Consequences
+------------
+
+This module will use a fixed set of tools as developed in python3-pip-skeleton
+and can pull from this skeleton to update the packaging to the latest techniques.
+
+As such, the developer environment may have changed, the following could be
+different:
+
+- linting
+- formatting
+- pip venv setup
+- CI/CD

153_fix_docs_build/_sources/developer/how-to/build-docs.rst.txt

@@ -0,0 +1,38 @@
+Build the docs using sphinx
+===========================
+
+You can build the `sphinx`_ based docs from the project directory by running::
+
+    $ tox -e docs
+
+This will build the static docs on the ``docs`` directory, which includes API
+docs that pull in docstrings from the code.
+
+.. seealso::
+
+    `documentation_standards`
+
+The docs will be built into the ``build/html`` directory, and can be opened
+locally with a web browser::
+
+    $ firefox build/html/index.html
+
+Autobuild
+---------
+
+You can also run an autobuild process, which will watch your ``docs``
+directory for changes and rebuild whenever it sees changes, reloading any
+browsers watching the pages::
+
+    $ tox -e docs autobuild
+
+You can view the pages at localhost::
+
+    $ firefox http://localhost:8000
+
+If you are making changes to source code too, you can tell it to watch
+changes in this directory too::
+
+    $ tox -e docs autobuild -- --watch src
+
+.. _sphinx: https://www.sphinx-doc.org/

153_fix_docs_build/_sources/developer/how-to/contribute.rst.txt

@@ -0,0 +1 @@
+.. include:: ../../../.github/CONTRIBUTING.rst

153_fix_docs_build/_sources/developer/how-to/lint.rst.txt

@@ -0,0 +1,39 @@
+Run linting using pre-commit
+============================
+
+Code linting is handled by black_ and ruff_ run under pre-commit_.
+
+Running pre-commit
+------------------
+
+You can run the above checks on all files with this command::
+
+    $ tox -e pre-commit
+
+Or you can install a pre-commit hook that will run each time you do a ``git
+commit`` on just the files that have changed::
+
+    $ pre-commit install
+
+It is also possible to `automatically enable pre-commit on cloned repositories <https://pre-commit.com/#automatically-enabling-pre-commit-on-repositories>`_.
+This will result in pre-commits being enabled on every repo your user clones from now on.
+
+Fixing issues
+-------------
+
+If black reports an issue you can tell it to reformat all the files in the
+repository::
+
+    $ black .
+
+Likewise with ruff::
+
+    $ ruff --fix .
+
+Ruff may not be able to automatically fix all issues; in this case, you will have to fix those manually.
+
+VSCode support
+--------------
+
+The ``.vscode/settings.json`` will run black formatting as well as
+ruff checking on save. Issues will be highlighted in the editor window.

153_fix_docs_build/_sources/developer/how-to/make-release.rst.txt

@@ -0,0 +1,16 @@
+Make a release
+==============
+
+To make a new release, please follow this checklist:
+
+- Choose a new PEP440 compliant release number (see https://peps.python.org/pep-0440/)
+- Go to the GitHub release_ page
+- Choose ``Draft New Release``
+- Click ``Choose Tag`` and supply the new tag you chose (click create new tag)
+- Click ``Generate release notes``, review and edit these notes
+- Choose a title and click ``Publish Release``
+
+Note that tagging and pushing to the main branch has the same effect except that
+you will not get the option to edit the release notes.
+
+.. _release: https://github.com/DiamondLightSource/python3-pip-skeleton/releases

153_fix_docs_build/_sources/developer/how-to/pin-requirements.rst.txt

@@ -0,0 +1,74 @@
+Pinning Requirements
+====================
+
+Introduction
+------------
+
+By design this project only defines dependencies in one place, i.e. in
+the ``requires`` table in ``pyproject.toml``.
+
+In the ``requires`` table it is possible to pin versions of some dependencies
+as needed. For library projects it is best to leave pinning to a minimum so
+that your library can be used by the widest range of applications.
+
+When CI builds the project it will use the latest compatible set of
+dependencies available (after applying your pins and any dependencies' pins).
+
+This approach means that there is a possibility that a future build may
+break because an updated release of a dependency has made a breaking change.
+
+The correct way to fix such an issue is to work out the minimum pinning in
+``requires`` that will resolve the problem. However this can be quite hard to
+do and may be time consuming when simply trying to release a minor update.
+
+For this reason we provide a mechanism for locking all dependencies to
+the same version as a previous successful release. This is a quick fix that
+should guarantee a successful CI build.
+
+Finding the lock files
+----------------------
+
+Every release of the project will have a set of requirements files published
+as release assets.
+
+For example take a look at the release page for python3-pip-skeleton-cli here:
+https://github.com/DiamondLightSource/python3-pip-skeleton-cli/releases/tag/3.3.0
+
+There is a list of requirements*.txt files showing as assets on the release.
+
+There is one file for each time the CI installed the project into a virtual
+environment. There are multiple of these as the CI creates a number of
+different environments.
+
+The files are created using ``pip freeze`` and will contain a full list
+of the dependencies and sub-dependencies with pinned versions.
+
+You can download any of these files by clicking on them. It is best to use
+the one that ran with the lowest Python version as this is more likely to
+be compatible with all the versions of Python in the test matrix.
+i.e. ``requirements-test-ubuntu-latest-3.8.txt`` in this example.
+
+Applying the lock file
+----------------------
+
+To apply a lockfile:
+
+- copy the requirements file you have downloaded to the root of your
+  repository
+- rename it to requirements.txt
+- commit it into the repo
+- push the changes
+
+The CI looks for a requirements.txt in the root and will pass it to pip
+when installing each of the test environments. pip will then install exactly
+the same set of packages as the previous release.
+
+Removing dependency locking from CI
+-----------------------------------
+
+Once the reasons for locking the build have been resolved it is a good idea
+to go back to an unlocked build. This is because you get an early indication
+of any incoming problems.
+
+To restore unlocked builds in CI simply remove requirements.txt from the root
+of the repo and push.

153_fix_docs_build/_sources/developer/how-to/run-tests.rst.txt

@@ -0,0 +1,12 @@
+Run the tests using pytest
+==========================
+
+Testing is done with pytest_. It will find functions in the project that `look
+like tests`_, and run them to check for errors. You can run it with::
+
+    $ tox -e pytest
+
+It will also report coverage to the commandline and to ``cov.xml``.
+
+.. _pytest: https://pytest.org/
+.. _look like tests: https://docs.pytest.org/explanation/goodpractices.html#test-discovery

153_fix_docs_build/_sources/developer/how-to/static-analysis.rst.txt

@@ -0,0 +1,8 @@
+Run static analysis using mypy
+==============================
+
+Static type analysis is done with mypy_. It checks type definition in source
+files without running them, and highlights potential issues where types do not
+match. You can run it with::
+
+    $ tox -e mypy

153_fix_docs_build/_sources/developer/how-to/test-container.rst.txt

@@ -0,0 +1,25 @@
+Container Local Build and Test
+==============================
+
+CI builds a runtime container for the project. The local tests
+checks available via ``tox -p`` do not verify this because not
+all developers will have docker installed locally.
+
+If CI is failing to build the container, then it is best to fix and
+test the problem locally. This would require that you have docker
+or podman installed on your local workstation.
+
+In the following examples the command ``docker`` is interchangeable with
+``podman`` depending on which container cli you have installed.
+
+To build the container and call it ``test``::
+
+    cd <root of the project>
+    docker build -t test .
+
+To verify that the container runs::
+
+    docker run -it test --help
+
+You can pass any other command line parameters to your application
+instead of --help.

153_fix_docs_build/_sources/developer/how-to/update-tools.rst.txt

@@ -0,0 +1,16 @@
+Update the tools
+================
+
+This module is merged with the python3-pip-skeleton_. This is a generic
+Python project structure which provides a means to keep tools and
+techniques in sync between multiple Python projects. To update to the
+latest version of the skeleton, run::
+
+    $ git pull --rebase=false https://github.com/DiamondLightSource/python3-pip-skeleton
+
+Any merge conflicts will indicate an area where something has changed that
+conflicts with the setup of the current module. Check the `closed pull requests
+<https://github.com/DiamondLightSource/python3-pip-skeleton/pulls?q=is%3Apr+is%3Aclosed>`_
+of the skeleton module for more details.
+
+.. _python3-pip-skeleton: https://DiamondLightSource.github.io/python3-pip-skeleton

153_fix_docs_build/_sources/developer/index.rst.txt

@@ -0,0 +1,64 @@
+Developer Guide
+===============
+
+Documentation is split into four categories, also accessible from links in the
+side-bar.
+
+.. grid:: 2
+    :gutter: 4
+
+    .. grid-item-card:: :material-regular:`directions_run;3em`
+
+        .. toctree::
+            :caption: Tutorials
+            :maxdepth: 1
+
+            tutorials/dev-install
+
+        +++
+
+        Tutorials for getting up and running as a developer.
+
+    .. grid-item-card:: :material-regular:`task;3em`
+
+        .. toctree::
+            :caption: How-to Guides
+            :maxdepth: 1
+
+            how-to/contribute
+            how-to/build-docs
+            how-to/run-tests
+            how-to/static-analysis
+            how-to/lint
+            how-to/update-tools
+            how-to/make-release
+            how-to/pin-requirements
+            how-to/test-container
+
+        +++
+
+        Practical step-by-step guides for day-to-day dev tasks.
+
+    .. grid-item-card:: :material-regular:`apartment;3em`
+
+        .. toctree::
+            :caption: Explanations
+            :maxdepth: 1
+
+            explanations/decisions
+
+        +++
+
+        Explanations of how and why the architecture is why it is.
+
+    .. grid-item-card:: :material-regular:`description;3em`
+
+        .. toctree::
+            :caption: Reference
+            :maxdepth: 1
+
+            reference/standards
+
+        +++
+
+        Technical reference material on standards in use.