convert to myst MD

.github/CONTRIBUTING.md

@@ -1,27 +1,23 @@
-# Contribute to the project
+# Contributing to the project
 
 Contributions and issues are most welcome! All issues and pull requests are
-handled through [GitHub](https://github.com/epics-containers/epics-containers.github.io/issues). Also, please check for any existing issues before
+handled through [GitHub]. Also, please check for any existing issues before
 filing a new one. If you have a great idea but it involves big changes, please
 file a ticket before making a pull request! We want to make sure you don't spend
 your time coding something that might not fit the scope of the project.
 
 ## Issue or Discussion?
 
-Github also offers [discussions](https://github.com/epics-containers/epics-containers.github.io/discussions) as a place to ask questions and share ideas. If
+Github also offers [discussions] as a place to ask questions and share ideas. If
 your issue is open ended and it is not obvious when it can be "closed", please
 raise it as a discussion instead.
 
-## Code Coverage
+## Developer guide
 
-While 100% code coverage does not make a library bug-free, it significantly
-reduces the number of easily caught bugs! Please make sure coverage remains the
-same or is improved by a pull request!
+The [Developer Guide] contains information on setting up a development
+environment, building docs and what standards the documentation
+should follow.
 
-## Developer Information
-
-It is recommended that developers use a [vscode devcontainer](https://code.visualstudio.com/docs/devcontainers/containers). This repository contains configuration to set up a containerized development environment that suits its own needs.
-
-This project was created using the [Diamond Light Source Copier Template](https://github.com/DiamondLightSource/python-copier-template) for Python projects.
-
-For more information on common tasks like setting up a developer environment, running the tests, and setting a pre-commit hook, see the template's [How-to guides](https://diamondlightsource.github.io/python-copier-template/1.3.0/how-to.html).
+[developer guide]: https://epics-containers.github.io/main/developer/how-to/contribute.html
+[discussions]: https://github.com/epics-containers/epics-containers.github.io/discussions
+[github]: https://github.com/epics-containers/epics-containers.github.io/issues

docs/conf.py

@@ -36,7 +36,10 @@
 ]
 
 # So we can use the ::: syntax
-myst_enable_extensions = ["colon_fence"]
+myst_enable_extensions = [
+    "colon_fence",
+    "deflist",
+]
 
 # If true, Sphinx will warn about all references where the target cannot
 # be found.

docs/explanations/decisions/0003-use-substitution-files.md

@@ -0,0 +1,48 @@
+# 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:
+
+```
+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.

docs/explanations/decisions/0004-autosave-req-files.rst → docs/explanations/decisions/0004-autosave-req-files.md

@@ -1,27 +1,23 @@
-4. How to configure autosave for IOCs
-=====================================
+# 4. How to configure autosave for IOCs
 
 Date: 2023-11-30
 
-Status
-------
+## Status
 
 Accepted
 
-Context
--------
+## 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
---------
+## Decision
 
 We will go with req files for the following reasons:
 
-- https://epics.anl.gov/tech-talk/2019/msg01600.php
+- <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
@@ -38,8 +34,6 @@ 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
-------------
+## Consequences
 
 Everything is nice and simple.
-

docs/explanations/decisions/0005-python-scripting.rst → docs/explanations/decisions/0005-python-scripting.md

@@ -1,21 +1,18 @@
-5. Use Python for scripting inside and outside containers
-=========================================================
+# 5. Use Python for scripting inside and outside containers
 
 Date: 2022-11-30
 
-Status
-------
+## Status
 
 Accepted
 
-Context
--------
+## Context
 
-Inside the container, we use the ``ibek`` tool for scripting. Outside we
-use ``ec`` from ``epics-containers-cli``.
+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,
+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
@@ -33,12 +30,10 @@ python for the following reasons:
 - 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
---------
+## Decision
 
 We always prefer Python and keep bash scripts to a minimum
 
-Consequences
-------------
+## Consequences
 
 Scripting is much easier to maintain and is more reliable.

docs/explanations/docs-structure.rst → docs/explanations/docs-structure.md

@@ -1,11 +1,10 @@
-About the documentation
------------------------
+# About the documentation
 
-  :material-regular:`format_quote;2em`
-
-  The Grand Unified Theory of Documentation
-
-  -- David Laing
+> {material-regular}`format_quote;2em`
+>
+> The Grand Unified Theory of Documentation
+>
+> <p class="attribution">-David Laing</p>
 
 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.
@@ -15,4 +14,4 @@ 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>`_
+[More information on this topic.](https://documentation.divio.com)