deploy: 975438f

0.8.0/.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: ae2656d73f5908d591e89c563442dea1
+tags: 645f666f9bcd5a90fca523b33c5a78b7

0.8.0/_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/*

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

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

@@ -0,0 +1,35 @@
+2. Adopt epics-containers.github.io for project structure
+=========================================================
+
+Date: 2022-02-18
+
+Status
+------
+
+Accepted
+
+Context
+-------
+
+We should use the following `pip-skeleton <https://github.com/epics-containers/epics-containers.github.io>`_.
+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 epics-containers.github.io
+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

0.8.0/_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 browse::
+
+    $ 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/

0.8.0/_sources/developer/how-to/contribute.rst.txt

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

0.8.0/_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/epics-containers/epics-containers.github.io/releases

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

0.8.0/_sources/developer/index.rst.txt

@@ -0,0 +1,59 @@
+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/update-tools
+            how-to/make-release
+
+        +++
+
+        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.

0.8.0/_sources/developer/reference/standards.rst.txt

@@ -0,0 +1,51 @@
+Standards
+=========
+
+This document defines the code and documentation standards used in this
+repository.
+
+
+.. _documentation_standards:
+
+Documentation Standards
+-----------------------
+
+Docstrings are pre-processed using the Sphinx Napoleon extension. As such,
+google-style_ is considered as standard for this repository. Please use type
+hints in the function signature for types. For example:
+
+.. code:: python
+
+    def func(arg1: str, arg2: int) -> bool:
+        """Summary line.
+
+        Extended description of function.
+
+        Args:
+            arg1: Description of arg1
+            arg2: Description of arg2
+
+        Returns:
+            Description of return value
+        """
+        return True
+
+.. _google-style: https://sphinxcontrib-napoleon.readthedocs.io/en/latest/index.html#google-vs-numpy
+
+Documentation is contained in the ``docs`` directory and extracted from
+docstrings of the API.
+
+Docs follow the underlining convention::
+
+    Headling 1 (page title)
+    =======================
+
+    Heading 2
+    ---------
+
+    Heading 3
+    ~~~~~~~~~
+
+.. seealso::
+
+    How-to guide `../how-to/build-docs`

0.8.0/_sources/developer/tutorials/dev-install.rst.txt

@@ -0,0 +1,62 @@
+Developer Contributing
+======================
+
+This project is documentation only. However the below steps set up a virtual
+python environment with the required tools to generate the sphinx documentation.
+
+Other projects in this repository do contain code and will have their own
+details on how to build and test them.
+
+These instructions will take you through the minimal steps required to get a dev
+environment setup, so you can build the documentation locally.
+
+Once completed see `../how-to/build-docs` for how to build the documentation.
+
+Clone the repository
+--------------------
+
+First clone the repository locally using `Git
+<https://git-scm.com/downloads>`_::
+
+    $ git clone git://github.com/epics-containers/epics-containers.github.io.git
+
+Install dependencies
+--------------------
+
+You can choose to either develop on the host machine using a `venv` (which
+requires python 3.8 or later) or to run in a container under `VSCode
+<https://code.visualstudio.com/>`_
+
+.. tab-set::
+
+    .. tab-item:: Local virtualenv
+
+        .. code::
+
+            $ cd epics-containers.github.io
+            $ python3 -m venv venv
+            $ source venv/bin/activate
+            $ pip install -e '.[dev]'
+
+    .. tab-item:: VSCode devcontainer
+
+        .. code::
+
+            $ code epics-containers.github.io
+            # Click on 'Reopen in Container' when prompted
+            # Open a new terminal
+
+See what was installed
+----------------------
+
+To see a graph of the python package dependency tree type::
+
+    $ pipdeptree
+
+Build and check
+---------------
+
+Now you have a development environment you can run checks in a terminal::
+
+    $ tox -p
+