checking if TOC crashes due to orphaned pages

docs/explanations/decisions.rst

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

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

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

docs/explanations/decisions/0002-switched-to-pip-skeleton.rst

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

docs/how-to/contribute.rst

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

docs/how-to/make-release.rst

@@ -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/PandABlocks/PandABlocks.github.io/releases

docs/how-to/run-container.rst

@@ -0,0 +1,43 @@
+Run in a container
+==================
+
+A PandA Development container is available from on `Github Container reistry <https://ghcr.io/pandablocks/pandablocks-dev-container>`_.
+
+
+
+Starting the container
+----------------------
+
+To pull the container from github container registry ::
+
+    $ docker pull ghcr.io/pandablocks/pandablocks-dev-container:latest
+
+To get a released version, use a numbered release instead of ``latest``.
+
+Create three directories: 
+
+- ``REPO_DIR``, containing all the PandA repositories
+
+- ``VIVADO_DIR``, containing a Vivado installation
+
+- ``BUILD_DIR``, an empty directory
+
+The above directories will be mounted as volumes to the container as it is run with the following command:
+
+.. code-block:: bash
+
+    docker run --rm -it -v REPO_DIR:/repos:Z -v BUILD_DIR:/build:Z -v VIVADO_DIR:/scratch/Xilinx ghcr.io/pandablocks/pandablocks-dev-container /bin/bash
+
+The ``/repos``, ``/build``, and ``/scratch/Xilinx`` paths describe the container directories at which the mounts occur. 
+
+In each repo you will need to:
+
+.. code-block:: bash
+
+    cp CONFIG.example CONFIG
+
+.. note::
+
+    For the Vivado installation the container path will need to match your local system. 
+    i.e. if it is located in /FPGA/Xilinx you will use VIVADO_DIR:/FPGA/Xilinx 
+    and you will then need to edit CONFIG as appropriate.

docs/how-to/update-tools.rst

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

docs/reference/standards.rst

@@ -0,0 +1,8 @@
+Standards
+=========
+
+This document defines the code and documentation standards used in this
+repository.
+
+Code Standards
+--------------