Merge pull request #45 from epics-containers/dev

Removed or flagged redundant pages.
epics-containers · Oct 26, 2023 · 566a51e · 566a51e
2 parents f76ead7 + b202295
commit 566a51e
Show file tree

Hide file tree

Showing 26 changed files with 217 additions and 334 deletions.
diff --git a/docs/conf.py b/docs/conf.py
@@ -152,7 +152,7 @@
 # to complete as the docs build warns and fails.
 html_theme_options = dict(
     logo=dict(
-        text=project,
+        text="EPICS Containers",
     ),
     navigation_with_keys=True,
     use_edit_page_button=True,

diff --git a/docs/index.rst b/docs/index.rst
@@ -5,13 +5,9 @@
 
 Update for October 2023
 =======================
-The final round of improvements are done. The latest framework has
-become much simpler and has a good developer experience.
-
-**WARNING**
-
-The Tutorials are currently out of date and won't work. These are
-being updated now and will be available by end of November 2023.
+The tutorials are being updated to work with the improved framework.
+The first few are available now, take note of warnings about out of
+date tutorials.
 
 
 Communication

diff --git a/docs/user/explanations/kubernetes_cluster.rst b/docs/user/explanations/kubernetes_cluster.rst
@@ -37,7 +37,7 @@ Three cluster topologies were considered for this project.
 Current Approach
 ----------------
 
-DLS is currently investigating Cluster per Beamline as the preferred topology. We
+DLS is using Cluster per Beamline as the preferred topology. We
 will continue to have a central cluster for shared services but in addition will
 have a cluster per beamline and a cluster for the accelerator.
 

diff --git a/docs/user/explanations/repos.rst b/docs/user/explanations/repos.rst
diff --git a/docs/user/how-to/ibek-defs.rst → docs/user/how-to/ibek-support.rst b/docs/user/how-to/ibek-defs.rst → docs/user/how-to/ibek-support.rst
@@ -1,8 +1,9 @@
-Updating and Testing ibek-defs
-==============================
+Updating and Testing ibek-support
+=================================
 
-TODO: this is draft
-TODO: this uses a Diamond internal repo as an example
+.. Warning::
+
+    This is draft only and out of date. It will be updated soon.
 
 The ibek-defs repository contains ibek support yaml. Here is an example
 procedure for local testing of changes to support yaml in ibek-defs

diff --git a/docs/user/how-to/run_iocs.rst b/docs/user/how-to/run_iocs.rst
diff --git a/docs/user/how-to/update_templated.rst b/docs/user/how-to/update_templated.rst
diff --git a/docs/user/how-to/useful_k8s.rst b/docs/user/how-to/useful_k8s.rst
@@ -11,7 +11,8 @@ The dashboard gives you a nice GUI for exploring and controlling your cluster.
 It is very useful for new users to get an understanding of what Kubernetes
 has to offer.
 
-These commands should be run INSIDE the devcontainer.
+These commands should be run after you have set up your Kubernetes cluster and
+setup the environment variables as described in `../tutorials/setup_k8s`.
 
 Execute this on your workstation:
 
@@ -48,10 +49,6 @@ Then create the admin user and role by executing the following:
 
 Get a token for the user and copy the token into your clipboard.
 
-On k3s v1.23 and older::
-
-    kubectl -n kubernetes-dashboard describe secret admin-user-token | grep '^token'
-
 On k3s v1.24 and newer::
 
     kubectl -n kubernetes-dashboard create token admin-user

diff --git a/docs/user/images/bl01t-actions.png b/docs/user/images/bl01t-actions.png
diff --git a/docs/user/images/edm_sim.png b/docs/user/images/edm_sim.png
diff --git a/docs/user/index.rst b/docs/user/index.rst
@@ -17,8 +17,8 @@ side-bar.
             tutorials/setup_workstation
             tutorials/create_beamline
             tutorials/deploy_example
+            tutorials/create_ioc
             tutorials/ioc_changes
-            tutorials/release_beamline
             tutorials/generic_ioc
             tutorials/debug_generic_ioc
             tutorials/test_generic_ioc
@@ -36,13 +36,11 @@ side-bar.
             :caption: How-to Guides
             :maxdepth: 1
 
-            how-to/run_iocs
             how-to/debug
             how-to/contributing
             how-to/own_tools
             how-to/useful_k8s
-            how-to/update_templated
-            how-to/ibek-defs
+            how-to/ibek-support
 
         +++
 
@@ -59,7 +57,6 @@ side-bar.
             explanations/kubernetes_cluster
             explanations/docs-structure
             explanations/repositories
-            explanations/repos
 
         +++
 

diff --git a/docs/user/reference/ioc_helm_chart.rst b/docs/user/reference/ioc_helm_chart.rst
@@ -1,6 +1,10 @@
 IOC Helm Chart Details
 ======================
 
+.. Warning::
+
+    This page is out of date and will be updated soon.
+
 IOC instances are described using a helm chart which in turn generates
 a Kubernetes manifest to tell Kubernetes what resources to create in order
 to run the IOC instance.

diff --git a/docs/user/tutorials/create_beamline.rst b/docs/user/tutorials/create_beamline.rst
@@ -25,12 +25,14 @@ When the project ``bl01t`` is pushed to GitHub, continuous integration will
 verify that each of the IOCs in the beamline are valid by launching them
 with basic configuration.
 
-It's not feasible to run full system tests with these IOCs Instances
-because they are configured to run with real hardware on a beamline.
-But note that each of these IOC instances will be launched using a
+The tests on beamline repositories are basic at present. However the intention
+is that eventually each device on a beamline will be simulated using
+`Tickit <https://github.com/dls-controls/tickit>`_ and that the CI so system
+tests of each IOC against simulated hardware.
+
+Also note that each of these IOC instances will be launched using a
 Generic IOC image. Ideally the CI for each Generic IOC should have already run
-system tests against simulated hardware. (this is something we aspire to
-using simulations provided by `Tickit <https://github.com/dls-controls/tickit>`_)
+system tests against simulated (but not beamline specific) hardware.
 
 This beamline repo will be taken from a template that comes with a single example
 IOC and further steps in the following tutorials will teach you how to add your own.
@@ -123,7 +125,8 @@ to determine where to deploy IOCS and where to find container images etc.
 
 For details of what goes in this file see `../reference/environment`.
 For the purpose of this tutorial for ``bl01t`` you should have the following
-in your environment.sh:
+in your environment.sh (make sure you insert your GitHub account name
+where indicated):
 
 - SECTION 1:
 
@@ -171,8 +174,8 @@ Wrapping Up
 -----------
 
 You should now have a working beamline repository. It contains a single
-IOC Instance and that is only a non-functional example. In the following
-tutorials we will investigate the example and then create a real IOC Instance.
+IOC Instance which is a non-functional example. In the following
+tutorial we will investigate the example and then create a real IOC Instance.
 
 You can now push the repository up to GitHub and give it a version tag like this:
 
@@ -182,7 +185,7 @@ You can now push the repository up to GitHub and give it a version tag like this
     git commit -m "changed blxxi to bl01t"
     git push
     git tag 2023.11.1
-    git push --tags
+    git push origin 2023.11.1
 
 
 We use ``CalVer`` version numbers for beamline repositories and Generic IOCs.

diff --git a/docs/user/tutorials/create_ioc.rst b/docs/user/tutorials/create_ioc.rst
@@ -0,0 +1,15 @@
+Create a Working Example IOC Instance
+=====================================
+
+Introduction
+------------
+
+The last section covered deploying and managing the example Instance that
+came with the template beamline repository. Here we will create a new
+IOC Instance that implements a simulated detector.
+
+TODO - complete this.
+
+.. figure:: ../images/c2dv.png
+
+    the c2dv viewer showing an image from the example IOC
diff --git a/docs/user/tutorials/debug_generic_ioc.rst b/docs/user/tutorials/debug_generic_ioc.rst
@@ -1,6 +1,10 @@
 Debugging Generic IOC Builds
 ============================
 
+.. Warning::
+
+    This tutorial is out of date and will be updated soon.
+
 This tutorial is a continuation of `generic_ioc`. Here we will look into
 debugging failed builds and fix the issue we saw in the  previous tutorial.