Merge pull request #73 from epics-containers/2024-rework

Add How to make a Generic IOC tutorial
epics-containers · Jan 22, 2024 · 8e9b88f · 8e9b88f
2 parents 949aafd + fd08df7
commit 8e9b88f
Show file tree

Hide file tree

Showing 19 changed files with 948 additions and 378 deletions.
diff --git a/docs/conf.py b/docs/conf.py
@@ -15,7 +15,7 @@
 
 # General information about the project.
 project = "epics-containers.github.io"
-copyright = "2023, Diamond Light Source"
+copyright = "2024, Diamond Light Source"
 author = "Giles Knap"
 
 # The full version, including alpha/beta/rc tags.

diff --git a/docs/user/how-to/builder2ibek.rst b/docs/user/how-to/builder2ibek.rst
@@ -0,0 +1,18 @@
+Builder2ibek Conversion Tool
+============================
+
+.. warning::
+
+    This page is only relevant to DLS users who are converting an xml
+    builder beamline to epics-containers. i.e. those whose beamlines
+    have a BLxxY-BUILDER project.
+
+TODO: this page is WIP and will be updated by Feb 2024.
+
+``builder2ibek`` is a tool to convert DLS builder XML to ibek instance YAML.
+It is for working with converting IOC instances to epics-containers.
+
+At present (until a new python app distribution mechanism is in place) it
+is installed at DLS in the following location:
+
+``/dls_sw/work/python3/ec-venv/bin/builder2ibek``
diff --git a/docs/user/how-to/builder2ibek.support.rst b/docs/user/how-to/builder2ibek.support.rst
@@ -0,0 +1,108 @@
+Builder2ibek.support Conversion Tool
+====================================
+
+.. warning::
+
+    This page is only relevant to DLS users who are converting
+    a DLS support module with builder support into an epics-containers
+    Generic IOC. i.e. support modules that have an ``etc/builder.py`` file.
+
+TODO: this page is WIP and will be updated by Feb 2024.
+
+``builder2ibek.support`` is a tool to convert DLS builder support modules
+into ibek support YAML for the ``ibek-support`` repository.
+
+
+builder2ibek.support example
+----------------------------
+
+.. code:: bash
+
+    ./builder2ibek.support.py /dls_sw/prod/R3.14.12.7/support/lakeshore340/2-6 ioc-lakeshore340/ibek-support/lakeshore340/lakeshore340.yaml
+
+
+.. code-block:: xml
+
+    <?xml version="1.0" ?>
+    <components arch="linux-x86_64">
+        <devIocStats.devIocStatsHelper ioc="BL16I-EA-IOC-07" name="STATS"/>
+        <asyn.AsynIP name="p1" port="127.0.0.1:5400"/>
+        <lakeshore340.lakeshore340 ADDR="12" LOOP="1" P="BL16I-EA-LS340-01" PORT="p1" SCAN="5" TEMPSCAN="1" gda_desc="Lakeshore 340 Temperature Controller" gda_name="LS340b" name="lakeshore"/>
+        <EPICS_BASE.dbpf name="d1" pv="BL16I-EA-LS340-01:DISABLE" value="1"/>
+    </components>
+
+
+ .. code:: yaml
+
+    # yaml-language-server: $schema=https://github.com/epics-containers/ibek/releases/download/1.2.0/ibek.support.schema.json
+
+    module: lakeshore340
+
+    defs:
+
+    - name: lakeshore340
+        description: |-
+        Lakeshore 340 Temperature Controller
+        Notes: The temperatures in Kelvin are archived once every 10 secs.
+        args:
+
+        - type: str
+            name: P
+            description: |-
+            Prefix for PV name
+
+        - type: str
+            name: PORT
+            description: |-
+            Bus/Port Address (eg. ASYN Port).
+
+        - type: str
+            name: ADDR
+            description: |-
+            Address on the bus
+
+        - type: str
+            name: SCAN
+            description: |-
+            SCAN rate for non-temperature/voltage parameters.
+
+        - type: str
+            name: TEMPSCAN
+            description: |-
+            SCAN rate for the temperature/voltage readings
+
+        - type: id
+            name: name
+            description: |-
+            Object and gui association name
+
+        - type: str
+            name: gda_name
+            description: |-
+            Name in gda interface file (Default = )
+
+        - type: str
+            name: gda_desc
+            description: |-
+            Description in gda interface file (Default = )
+
+        - type: int
+            name: LOOP
+            description: |-
+            Which heater PID loop to control (Default = 1)
+            default: 1
+
+        databases:
+
+        - file: $(LAKESHORE340)/db/lakeshore340.template
+            args:
+            name:
+            SCAN:
+            gda_name:
+            P:
+            TEMPSCAN:
+            gda_desc:
+            PORT:
+            LOOP:
+            ADDR:
+
diff --git a/docs/user/how-to/phoebus.rst b/docs/user/how-to/phoebus.rst
@@ -9,4 +9,4 @@ This is the initial target for epics-containers GUIs, other OPI
 formats may be supported in the future.
 
 OPI file generation is work in progress and this page will be updated when
-it is ready (est Nov 2023).
+it is ready (est Feb 2024).
diff --git a/docs/user/index.rst b/docs/user/index.rst
@@ -22,7 +22,6 @@ side-bar.
             tutorials/ioc_changes1
             tutorials/ioc_changes2
             tutorials/ioc_changes3
-            tutorials/ioc_changes4
             tutorials/generic_ioc
             tutorials/debug_generic_ioc
             tutorials/test_generic_ioc
@@ -47,6 +46,8 @@ side-bar.
             how-to/own_tools
             how-to/useful_k8s
             how-to/ibek-support
+            how-to/builder2ibek
+            how-to/builder2ibek.support
 
         +++
 
@@ -76,10 +77,12 @@ side-bar.
             :maxdepth: 1
 
             reference/faq
+            reference/configuration
             reference/environment
             reference/cli
             reference/ioc_helm_chart
             reference/k8s_resources
+            reference/vscode_settings
 
         +++
 

diff --git a/docs/user/reference/configuration.rst b/docs/user/reference/configuration.rst
@@ -0,0 +1,18 @@
+Configuration for epics-containers
+==================================
+
+A collection of all the configuration points mentioned in the rest of this
+documentation.
+
+TODO: this needs completing - pull all configuration discussions into
+one place. Most of these will come from the original Setting up the
+Workspace document.
+
+
+Git Configuration
+-----------------
+
+.. code-block::
+
+    [url "ssh://[email protected]/"]
+            insteadOf = https://github.com/
diff --git a/docs/user/reference/ioc_helm_chart.rst b/docs/user/reference/ioc_helm_chart.rst
@@ -58,7 +58,7 @@ in this folder and what you would need to change in your new IOC instance:
 
 -   ``config`` this folder contains any files unique to this IOC instance. At
     runtime on the cluster when the Generic IOC image is running it will see
-    these files as mounted into the folder ``/repos/epics/ioc/config``.
+    these files as mounted into the folder ``/workspaces/epics/ioc/config``.
     In this case we have an EPICS startup script ``st.cmd`` only
     and the default behaviour is just to run the IOC binary and pass it
     ``st.cmd``.

diff --git a/docs/user/reference/vscode_settings.rst b/docs/user/reference/vscode_settings.rst
@@ -0,0 +1,34 @@
+Recommended VSCode Settings
+===========================
+
+I've picked a handful of my user settings which I think are useful for most
+people working on epics-containers.
+
+TODO: write up a description of why these are useful. Particularly with
+regards to auto discovery of git repos.
+
+.. code-block::
+
+    scm.repositories.visible: 10
+    git.repositoryScanMaxDepth: 0
+    git.openRepositoryInParentFolders: never
+    files.trimTrailingWhitespace: true
+    terminal.integrated.scrollback: 20000
+        dev.containers.defaultExtensions: [
+            "samuelcolvin.jinjahtml",
+            "moshfeu.compare-folders",
+            "GitHub.copilot",
+            "charliermarsh.ruff",
+            "Gruntfuggly.todo-tree",
+            "streetsidesoftware.code-spell-checker",
+            "eamodio.gitlens",
+            "tamasfe.even-better-toml",
+            "redhat.vscode-yaml",
+            "ryanluker.vscode-coverage-gutters",
+            "mhutchie.git-graph",
+            "ms-vscode.makefile-tools"
+            "peakchen90.open-html-in-browser",
+        ],
+    "[yaml]": {
+        "editor.defaultFormatter": "redhat.vscode-yaml"
+    },
diff --git a/docs/user/tutorials/create_beamline.rst b/docs/user/tutorials/create_beamline.rst
@@ -66,7 +66,7 @@ We will then step through the changes that are required to make it your own.
 NOTE: for these tutorials we will use your personal GitHub Account to
 store everything we do, all source repositories and container images. For
 production, each facility will need its own policy for where to store these
-assets. See `../explanations/repositories`.
+assets. See ``../explanations/workspacesitories``.
 
 Steps
 -----
@@ -110,10 +110,15 @@ Steps
     #. change the beamline name in the two bash scripts in the ``services``
        directory.
 
+    #. change the beamline name in ``beamline-chart/values.yaml``
+
     #. add some meaningful configuration to the example IOCs config folder
        ``iocs/bl01t-ea-ioc-01/config/ioc.yaml``. We will do this in the
        next tutorial.
 
+Much of the above can be achieved with a global find and replace of 'xxi' with
+'01t'.
+
 Environment.sh
 ~~~~~~~~~~~~~~
 
@@ -175,6 +180,14 @@ Open both files in ``services/`` and replace blxxi with bl01t.
 
 TODO: add support for local docker installations of these services.
 
+Change the Beamline Name in the Helm Chart
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+The file ``beamline-chart/values.yaml`` contains the configuration values
+for the helm chart that is used to deploy the beamline. You can change
+the values ``blxxi`` to ``bl01t`` in here. But this will not be relevant until
+we get to the Kubernetes tutorial when the deployment is done using helm.
+
 Wrapping Up
 -----------
 
@@ -189,8 +202,8 @@ You can now push the repository up to GitHub and give it a version tag like this
     git add .
     git commit -m "changed blxxi to bl01t"
     git push
-    git tag 2023.11.1
-    git push origin 2023.11.1
+    git tag 2024.1.1
+    git push origin 2024.1.1
 
 
 We use ``CalVer`` version numbers for beamline repositories and Generic IOCs.
@@ -201,3 +214,9 @@ CalVer is described here: https://calver.org/ and is used where semantic
 versioning is not appropriate because the repository contains a mix of
 dependencies and does not have a clear API.
 
+Note that 2024.1.1 represents the time that this tutorial was last updated.
+For completeness you could use the current year and month instead. You
+are also free to choose your own versioning scheme as this is not enforced by
+any of the epics-containers tools.
+
+
diff --git a/docs/user/tutorials/create_ioc.rst b/docs/user/tutorials/create_ioc.rst
@@ -45,7 +45,7 @@ This should launch vscode and open the values.yaml file. Add the following:
 
 .. code-block:: yaml
 
-    image: ghcr.io/epics-containers/ioc-adsimdetector-linux-runtime:2023.11.1
+    image: ghcr.io/epics-containers/ioc-adsimdetector-linux-runtime:2024.1.1
 
 This tells the IOC Instance to run in the ``ioc-adsimdetector-linux-runtime``
 container. This container was built by the Generic IOC source repo here
@@ -71,7 +71,7 @@ To recap, we have two python CLI tools for supporting ``epics-containers``:
     - Generating startup scripts and EPICS databases at container runtime
       from *IOC yaml* files.
     - Fetching and compiling support modules at build time.
-    - Other build time utilities such as creating and compiling IOC source and
+    - Other build time utilities such as
       extracting runtime assets for the runtime container target.
 
 :ec: provides developer support *outside* of the container such as:
@@ -190,7 +190,7 @@ This should launch vscode and open the ioc.yaml file. Add the following:
 
 .. code:: yaml
 
-    # yaml-language-server: $schema=https://github.com/epics-containers/ioc-adsimdetector/releases/download/2023.11.1/ibek.ioc.schema.json
+    # yaml-language-server: $schema=https://github.com/epics-containers/ioc-adsimdetector/releases/download/2024.1.1/ibek.ioc.schema.json
 
     ioc_name: bl01t-ea-ioc-02
     description: Example simulated camera for BL01T
@@ -320,15 +320,15 @@ That is because every Generic IOC publishes an *IOC schema* that describes
 the set of entities that an instance of that IOC may instantiate.
 
 The Generic IOC we used was released at this location:
-https://github.com/epics-containers/ioc-adsimdetector/releases/tag/2023.11.1.
+https://github.com/epics-containers/ioc-adsimdetector/releases/tag/2024.1.1.
 This page includes the assets that are published as part of the release and
 one of those is ``ibek.ioc.schema.json``. This is the *IOC schema* for the
 ``ioc-adsimdetector`` Generic IOC. This is what we referred to at the top of
 our *IOC yaml* file like this:
 
 .. code:: yaml
 
-    # yaml-language-server: $schema=https://github.com/epics-containers/ioc-adsimdetector/releases/download/2023.11.1/ibek.ioc.schema.json
+    # yaml-language-server: $schema=https://github.com/epics-containers/ioc-adsimdetector/releases/download/2024.1.1/ibek.ioc.schema.json
 
 When editing with a YAML aware editor like VSCode this will enable auto
 completion and validation of the *IOC yaml* file. To enable this in VSCode

diff --git a/docs/user/tutorials/debug_generic_ioc.rst b/docs/user/tutorials/debug_generic_ioc.rst
@@ -44,7 +44,7 @@ command.
 
 .. code-block:: bash
 
-    cd /repos/epics/support/adurl
+    cd /workspaces/epics/support/adurl
     make
 
 You should see the same error again.
@@ -81,7 +81,7 @@ need to set the variable ``GRAPHICSMAGICK_INCLUDE`` in
 We can see from the ``apt-file`` output that the header file is in
 ``/usr/include/GraphicsMagick`` which is not a default include path.
 Therefore we need to edit this file inside our Generic IOC container:
-``/repos/epics/support/adurl/configure/CONFIG_SITE.linux-x86_64.Common``
+``/workspaces/epics/support/adurl/configure/CONFIG_SITE.linux-x86_64.Common``
 
 .. _CONFIG_SITE.local: https://areadetector.github.io/areaDetector/install_guide.html#edit-config-site-local-and-optionally-config-site-local-epics-host-arch
 
@@ -95,8 +95,8 @@ you like from the Ubuntu repositories.
 
 HOWEVER, there is a much easier way ...
 
-When you launch containers with ``ec`` commands the ``/repos`` folder is
-synchronized to a local folder ioc-XXX/repos and that is mounted into the
+When you launch containers with ``ec`` commands the ``/workspaces`` folder is
+synchronized to a local folder ioc-XXX/workspaces and that is mounted into the
 container. This means that you can edit files in the container using VSCode.
 The mounted repos folder also ensures that any changes you make inside the
 container are saved between invocations of the container.