deploy: a8db1ee

epics-containers · Jan 12, 2024 · 1a7fa87 · 1a7fa87
1 parent 94b10cf
commit 1a7fa87
Show file tree

Hide file tree

Showing 221 changed files with 45,121 additions and 0 deletions.
diff --git a/k8s-tutorials/.buildinfo b/k8s-tutorials/.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: dad512acab4a3fa0f23e02fd5a2f056b
+tags: 645f666f9bcd5a90fca523b33c5a78b7
diff --git a/k8s-tutorials/.doctrees/developer/explanations/decisions.doctree b/k8s-tutorials/.doctrees/developer/explanations/decisions.doctree
diff --git a/...als/.doctrees/developer/explanations/decisions/0001-record-architecture-decisions.doctree b/...als/.doctrees/developer/explanations/decisions/0001-record-architecture-decisions.doctree
diff --git a/...utorials/.doctrees/developer/explanations/decisions/0002-switched-to-pip-skeleton.doctree b/...utorials/.doctrees/developer/explanations/decisions/0002-switched-to-pip-skeleton.doctree
diff --git a/k8s-tutorials/.doctrees/developer/explanations/decisions/0003-use-substitution-files.doctree b/k8s-tutorials/.doctrees/developer/explanations/decisions/0003-use-substitution-files.doctree
diff --git a/k8s-tutorials/.doctrees/developer/explanations/decisions/0004-autosave-req-files.doctree b/k8s-tutorials/.doctrees/developer/explanations/decisions/0004-autosave-req-files.doctree
diff --git a/k8s-tutorials/.doctrees/developer/explanations/decisions/0005-python-scripting.doctree b/k8s-tutorials/.doctrees/developer/explanations/decisions/0005-python-scripting.doctree
diff --git a/k8s-tutorials/.doctrees/developer/how-to/build-docs.doctree b/k8s-tutorials/.doctrees/developer/how-to/build-docs.doctree
diff --git a/k8s-tutorials/.doctrees/developer/how-to/contribute.doctree b/k8s-tutorials/.doctrees/developer/how-to/contribute.doctree
diff --git a/k8s-tutorials/.doctrees/developer/how-to/make-release.doctree b/k8s-tutorials/.doctrees/developer/how-to/make-release.doctree
diff --git a/k8s-tutorials/.doctrees/developer/how-to/update-tools.doctree b/k8s-tutorials/.doctrees/developer/how-to/update-tools.doctree
diff --git a/k8s-tutorials/.doctrees/developer/index.doctree b/k8s-tutorials/.doctrees/developer/index.doctree
diff --git a/k8s-tutorials/.doctrees/developer/reference/standards.doctree b/k8s-tutorials/.doctrees/developer/reference/standards.doctree
diff --git a/k8s-tutorials/.doctrees/developer/tutorials/dev-install.doctree b/k8s-tutorials/.doctrees/developer/tutorials/dev-install.doctree
diff --git a/k8s-tutorials/.doctrees/environment.pickle b/k8s-tutorials/.doctrees/environment.pickle
diff --git a/k8s-tutorials/.doctrees/index.doctree b/k8s-tutorials/.doctrees/index.doctree
diff --git a/k8s-tutorials/.doctrees/user/explanations/docs-structure.doctree b/k8s-tutorials/.doctrees/user/explanations/docs-structure.doctree
diff --git a/k8s-tutorials/.doctrees/user/explanations/introduction.doctree b/k8s-tutorials/.doctrees/user/explanations/introduction.doctree
diff --git a/k8s-tutorials/.doctrees/user/explanations/ioc-source.doctree b/k8s-tutorials/.doctrees/user/explanations/ioc-source.doctree
diff --git a/k8s-tutorials/.doctrees/user/explanations/kubernetes_cluster.doctree b/k8s-tutorials/.doctrees/user/explanations/kubernetes_cluster.doctree
diff --git a/k8s-tutorials/.doctrees/user/explanations/net_protocols.doctree b/k8s-tutorials/.doctrees/user/explanations/net_protocols.doctree
diff --git a/k8s-tutorials/.doctrees/user/explanations/repositories.doctree b/k8s-tutorials/.doctrees/user/explanations/repositories.doctree
diff --git a/k8s-tutorials/.doctrees/user/how-to/contributing.doctree b/k8s-tutorials/.doctrees/user/how-to/contributing.doctree
diff --git a/k8s-tutorials/.doctrees/user/how-to/debug.doctree b/k8s-tutorials/.doctrees/user/how-to/debug.doctree
diff --git a/k8s-tutorials/.doctrees/user/how-to/ibek-support.doctree b/k8s-tutorials/.doctrees/user/how-to/ibek-support.doctree
diff --git a/k8s-tutorials/.doctrees/user/how-to/own_tools.doctree b/k8s-tutorials/.doctrees/user/how-to/own_tools.doctree
diff --git a/k8s-tutorials/.doctrees/user/how-to/phoebus.doctree b/k8s-tutorials/.doctrees/user/how-to/phoebus.doctree
diff --git a/k8s-tutorials/.doctrees/user/how-to/useful_k8s.doctree b/k8s-tutorials/.doctrees/user/how-to/useful_k8s.doctree
diff --git a/k8s-tutorials/.doctrees/user/index.doctree b/k8s-tutorials/.doctrees/user/index.doctree
diff --git a/k8s-tutorials/.doctrees/user/overview.doctree b/k8s-tutorials/.doctrees/user/overview.doctree
diff --git a/k8s-tutorials/.doctrees/user/reference/cli.doctree b/k8s-tutorials/.doctrees/user/reference/cli.doctree
diff --git a/k8s-tutorials/.doctrees/user/reference/environment.doctree b/k8s-tutorials/.doctrees/user/reference/environment.doctree
diff --git a/k8s-tutorials/.doctrees/user/reference/faq.doctree b/k8s-tutorials/.doctrees/user/reference/faq.doctree
diff --git a/k8s-tutorials/.doctrees/user/reference/ioc_helm_chart.doctree b/k8s-tutorials/.doctrees/user/reference/ioc_helm_chart.doctree
diff --git a/k8s-tutorials/.doctrees/user/reference/k8s_resources.doctree b/k8s-tutorials/.doctrees/user/reference/k8s_resources.doctree
diff --git a/k8s-tutorials/.doctrees/user/tutorials/create_beamline.doctree b/k8s-tutorials/.doctrees/user/tutorials/create_beamline.doctree
diff --git a/k8s-tutorials/.doctrees/user/tutorials/create_ioc.doctree b/k8s-tutorials/.doctrees/user/tutorials/create_ioc.doctree
diff --git a/k8s-tutorials/.doctrees/user/tutorials/debug_generic_ioc.doctree b/k8s-tutorials/.doctrees/user/tutorials/debug_generic_ioc.doctree
diff --git a/k8s-tutorials/.doctrees/user/tutorials/deploy_example.doctree b/k8s-tutorials/.doctrees/user/tutorials/deploy_example.doctree
diff --git a/k8s-tutorials/.doctrees/user/tutorials/dev_container.doctree b/k8s-tutorials/.doctrees/user/tutorials/dev_container.doctree
diff --git a/k8s-tutorials/.doctrees/user/tutorials/generic_ioc.doctree b/k8s-tutorials/.doctrees/user/tutorials/generic_ioc.doctree
diff --git a/k8s-tutorials/.doctrees/user/tutorials/ibek.doctree b/k8s-tutorials/.doctrees/user/tutorials/ibek.doctree
diff --git a/k8s-tutorials/.doctrees/user/tutorials/intro.doctree b/k8s-tutorials/.doctrees/user/tutorials/intro.doctree
diff --git a/k8s-tutorials/.doctrees/user/tutorials/ioc_changes1.doctree b/k8s-tutorials/.doctrees/user/tutorials/ioc_changes1.doctree
diff --git a/k8s-tutorials/.doctrees/user/tutorials/ioc_changes2.doctree b/k8s-tutorials/.doctrees/user/tutorials/ioc_changes2.doctree
diff --git a/k8s-tutorials/.doctrees/user/tutorials/ioc_changes3.doctree b/k8s-tutorials/.doctrees/user/tutorials/ioc_changes3.doctree
diff --git a/k8s-tutorials/.doctrees/user/tutorials/ioc_changes4.doctree b/k8s-tutorials/.doctrees/user/tutorials/ioc_changes4.doctree
diff --git a/k8s-tutorials/.doctrees/user/tutorials/rtems_ioc.doctree b/k8s-tutorials/.doctrees/user/tutorials/rtems_ioc.doctree
diff --git a/k8s-tutorials/.doctrees/user/tutorials/rtems_setup.doctree b/k8s-tutorials/.doctrees/user/tutorials/rtems_setup.doctree
diff --git a/k8s-tutorials/.doctrees/user/tutorials/setup_k8s.doctree b/k8s-tutorials/.doctrees/user/tutorials/setup_k8s.doctree
diff --git a/k8s-tutorials/.doctrees/user/tutorials/setup_workstation.doctree b/k8s-tutorials/.doctrees/user/tutorials/setup_workstation.doctree
diff --git a/k8s-tutorials/.doctrees/user/tutorials/support_module.doctree b/k8s-tutorials/.doctrees/user/tutorials/support_module.doctree
diff --git a/k8s-tutorials/.doctrees/user/tutorials/test_generic_ioc.doctree b/k8s-tutorials/.doctrees/user/tutorials/test_generic_ioc.doctree
diff --git a/k8s-tutorials/_downloads/00ddc08dee7879e828f8d56b6443500d/THBL04_talk.PDF b/k8s-tutorials/_downloads/00ddc08dee7879e828f8d56b6443500d/THBL04_talk.PDF
diff --git a/k8s-tutorials/_downloads/40056c2fdacaa7f3ef8f609a698d85b1/THBL04.PDF b/k8s-tutorials/_downloads/40056c2fdacaa7f3ef8f609a698d85b1/THBL04.PDF
diff --git a/k8s-tutorials/_images/argus3.jpg b/k8s-tutorials/_images/argus3.jpg
diff --git a/k8s-tutorials/_images/bl01t-actions.png b/k8s-tutorials/_images/bl01t-actions.png
diff --git a/k8s-tutorials/_images/c2dv.png b/k8s-tutorials/_images/c2dv.png
diff --git a/k8s-tutorials/_images/cabackwarder.png b/k8s-tutorials/_images/cabackwarder.png
diff --git a/k8s-tutorials/_images/caforwarder.png b/k8s-tutorials/_images/caforwarder.png
diff --git a/k8s-tutorials/_images/clusterHA.png b/k8s-tutorials/_images/clusterHA.png
diff --git a/k8s-tutorials/_images/ghcr.png b/k8s-tutorials/_images/ghcr.png
diff --git a/k8s-tutorials/_images/github_actions2.png b/k8s-tutorials/_images/github_actions2.png
diff --git a/k8s-tutorials/_images/ibek-defs-notes.png b/k8s-tutorials/_images/ibek-defs-notes.png
diff --git a/k8s-tutorials/_images/kubeadm-ha-topology-stacked-etcd.png b/k8s-tutorials/_images/kubeadm-ha-topology-stacked-etcd.png
diff --git a/k8s-tutorials/_images/millie.png b/k8s-tutorials/_images/millie.png
diff --git a/k8s-tutorials/_images/repos_folder.png b/k8s-tutorials/_images/repos_folder.png
diff --git a/k8s-tutorials/_images/vcxsrv.png b/k8s-tutorials/_images/vcxsrv.png
diff --git a/k8s-tutorials/_sources/developer/explanations/decisions.rst.txt b/k8s-tutorials/_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/*
diff --git a/...ces/developer/explanations/decisions/0001-record-architecture-decisions.rst.txt b/...ces/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.
diff --git a/..._sources/developer/explanations/decisions/0002-switched-to-pip-skeleton.rst.txt b/..._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 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
diff --git a/...s/_sources/developer/explanations/decisions/0003-use-substitution-files.rst.txt b/...s/_sources/developer/explanations/decisions/0003-use-substitution-files.rst.txt
@@ -0,0 +1,55 @@
+3. Use of substitution files to generate EPICS Databases
+========================================================
+
+Date: 2023-11-30
+
+Status
+------
+
+Accepted
+
+Context
+-------
+
+There are two proposals for how EPICS Databases should be generated:
+
+1.  At IOC startup ``ibek`` should generate a substitution file that describes the
+    required Databases.
+
+    The IOC instance yaml combined with the definitions from support module yaml
+    controls what the generated substitution file will look like.
+
+    ``ibek`` will then execute ``msi`` to generate the Databases from the
+    substitution file.
+
+2.  The dbLoadRecord calls in the startup script will pass all macro substitutions
+    in-line. Removing the need for a substitution file.
+
+
+Decision
+--------
+
+Proposal 1 is accepted.
+
+Some template files such as those in the ``pmac`` support module use the
+following pattern:
+
+.. code-block::
+
+    substitute "P=$(PMAC):, M=CS$(CS):M1, ADDR=1, DESC=CS Motor A"
+    include "pmacDirectMotor.template"
+
+This pattern is supported by msi but not by the EPICS dbLoadRecord command which
+does not recognise the ``substitute`` command.
+
+
+Consequences
+------------
+
+An extra file ``ioc.subst`` is seen in the runtime directory. In reality this
+is easier to read than a full Database file. So can be useful for debugging.
+
+Finally those developers who are unable to use ``ibek yaml`` for some reason can
+supply their own substitution file and ibek will expand it at runtime. This is
+much more compact that supplying a full Database file and important due to the
+1MB limit on K8S ConfigMaps.
diff --git a/...rials/_sources/developer/explanations/decisions/0004-autosave-req-files.rst.txt b/...rials/_sources/developer/explanations/decisions/0004-autosave-req-files.rst.txt
@@ -0,0 +1,45 @@
+4. How to configure autosave for IOCs
+=====================================
+
+Date: 2023-11-30
+
+Status
+------
+
+Accepted
+
+Context
+-------
+
+There is a choice of supplying the list of PVs to autosave by:
+
+- adding info tags to the Database Templates
+- supplying a raw req file with list of PVs to autosave
+
+Decision
+--------
+
+We will go with req files for the following reasons:
+
+- https://epics.anl.gov/tech-talk/2019/msg01600.php
+- adding info tags would require upstream changes to most support modules
+- default req files are already supplied in many support modules
+- req files are in common use and many facilities may already have their own
+  req files for support modules.
+
+We expect to autogenerate the list of PVs to autosave from the IOC's. We could
+therefore generate a Database override file which adds info tags. But it is
+simpler to just generate a req file.
+
+The mechanism for using req files is that defaults will come from the support
+module or from the generic IOC if the support module does not supply a req file.
+
+Then override files can exist at the beamline level and / or at the IOC
+instance level. These will simply take the form of a req file with the same
+name as the one it is overriding.
+
+Consequences
+------------
+
+Everything is nice and simple.
+
diff --git a/...torials/_sources/developer/explanations/decisions/0005-python-scripting.rst.txt b/...torials/_sources/developer/explanations/decisions/0005-python-scripting.rst.txt
@@ -0,0 +1,44 @@
+5. Use Python for scripting inside and outside containers
+=========================================================
+
+Date: 2022-11-30
+
+Status
+------
+
+Accepted
+
+Context
+-------
+
+Inside the container, we use the ``ibek`` tool for scripting. Outside we
+use ``ec`` from ``epics-containers-cli``.
+
+Much of what these tools do is
+call command line tools like ``docker``, ``helm``, ``kubectl``, compilers,
+etc. This seems like a natural fit for bash scripts.
+
+These features were originally implemented in bash but were converted to
+python for the following reasons:
+
+- python provides for much richer command line arguments
+- it is also much easier to provide rich help
+- managing errors is vastly improved with exception handling
+- the unit testing framework allows good test coverage in continuous integration
+- complex string handling is a common requirement and is much easier in python
+- there is a clear versioning strategy and packages can be installed with pip,
+  meaning that you can check which version of the script you are running and
+  report bugs against a specific version
+- the code is much easier to read and maintain
+- because the packages can be pip installed they can be used in CI and inside
+  multiple containers without having to copy the scripts around
+
+Decision
+--------
+
+We always prefer Python and keep bash scripts to a minimum
+
+Consequences
+------------
+
+Scripting is much easier to maintain and is more reliable.
diff --git a/k8s-tutorials/_sources/developer/how-to/build-docs.rst.txt b/k8s-tutorials/_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/
diff --git a/k8s-tutorials/_sources/developer/how-to/contribute.rst.txt b/k8s-tutorials/_sources/developer/how-to/contribute.rst.txt
@@ -0,0 +1 @@
+.. include:: ../../../.github/CONTRIBUTING.rst
diff --git a/k8s-tutorials/_sources/developer/how-to/make-release.rst.txt b/k8s-tutorials/_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
diff --git a/k8s-tutorials/_sources/developer/how-to/update-tools.rst.txt b/k8s-tutorials/_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
diff --git a/k8s-tutorials/_sources/developer/index.rst.txt b/k8s-tutorials/_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.