add warnings to out of date tutorials

Author: gilesknap

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:
 

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.
 

docs/user/tutorials/deploy_example.rst

@@ -1,14 +1,29 @@
 Deploy The Example IOC
 ======================
 
-.. warning::
+.. Warning::
 
-    This information is out of date and will be updated soon.
+    This tutorial is out of date and will be updated soon.
+
+Introduction
+------------
+
+This tutorial will show you how to deploy some IOC Instances to the test
+beamline bl01t. You will need to have your own bl01t beamline repository
+from the previous tutorial.
+
+For these early tutorials we are not using Kubernetes and instead are deploying
+IOCs to the local docker or podman instance. So for the this tutorial we
+shall pretend that your workstation is one of the IOC servers on the fictitious
+beamline BL01T.
 
 Take a Look at Your Project's Continuous Integration
 ----------------------------------------------------
 
-TODO
+Before we change anything we shall make sure that the beamline repository CI
+is working as expected. To do this go to the following URL:
+
+-
 
 Set up Environment for BL01T Beamline
 -------------------------------------
@@ -23,12 +38,13 @@ the following to the end of you $HOME/.bash_profile file:
 
     export PATH="$PATH:~/.local/bin"
 
-Then follow these steps:
+Then follow these steps (make sure you insert your GitHub account name
+where indicated):
 
 .. code-block:: bash
 
     cd /tmp
-    curl -o ~/.local/bin/bl01t https://raw.githubusercontent.com/epics-containers/bl38p/main/environment.sh?token=$(date +%s)
+    curl -o ~/.local/bin/bl01t https://raw.githubusercontent.com/**YOUR GITHUB ACCOUNT**/bl01t/main/environment.sh?token=$(date +%s)
     . ~/.bash_profile
     . bl01t
 

docs/user/tutorials/generic_ioc.rst

@@ -1,6 +1,10 @@
 Create a Generic IOC
 ====================
 
+.. Warning::
+
+    This tutorial is out of date and will be updated soon.
+
 In this tutorial we will learn how to create a Generic IOC container image and
 test our changes locally before deploying it.
 

docs/user/tutorials/ibek.rst

@@ -10,9 +10,13 @@ TODO: do some of these titles belong in explanations or reference sections? If s
 What is IBEK
 ------------
 
-- IOC Builder for EPICS on Kubernetes
+IOC Builder for EPICS on Kubernetes. It is a python module which supports all
+the features of epics-containers required inside of generic IOC containers.
+It is used at container build time and container run time.
+
 - uses Support YAML to define what each support module can supply
 - uses IOC YAML to instantiate instances of support features that make up an IOC instances
+- provides build time functions for acquiring and compiling support modules
 
 Why Use IBEK
 ------------
@@ -27,22 +31,28 @@ Alternatives
 
 epics-containers supports out of the box dropping a startup script and
 substitution file into the config folder as an alternative to supplying
-ibek IOC YAML. But you can override start.sh and work in any way you choose
-at runtime.
+ibek IOC YAML. You can also override the default start.sh and work in any
+way you choose by placing a script called start.sh in the config folder.
 
-ibek-defs
----------
+ibek-support
+------------
 
 - defines the support modules YAML in a single place.
-- exists to avoid duplication of support module definitions
+- also supplies install.sh for each support module that defines where the source
+  can be found and how to build it.
+- exists to avoid duplication of support module definitions in Generic IOCs
 - and to avoid working on multiple support modules while kicking off epics-containers
-- in future YAML could be supplied in each support module itself - but until epics-containers is widely used, this is a good way to get started
-- the ibek-defs repo is added as a git-submodule to every Generic ioc (ioc-xxx) repo and in this ensures that a rebuild of a Generic ioc will be with a consistent set of YAML files until a developer explicitly updates the submodule.
+- the ibek-support repo is added as a git-submodule to every Generic ioc
+  (ioc-xxx) repo and in this ensures that a rebuild of a Generic ioc will be
+  with a consistent set of YAML files and install.sh files until a developer
+  explicitly updates the submodule.
 
-How to work on ibek-defs
-------------------------
+How to work on ibek-support
+---------------------------
 
-Building a new Generic ioc and making it compatible with ibek means creating ibek support YAML for all of its dependent support modules (where they do not already exist)
+Building a new Generic ioc and making it compatible with ibek means creating
+ibek support YAML for all of its dependent support modules
+(where they do not already exist)
 
 These steps assume you have a Generic ioc for ADUrl based on ioc_template as discussed in `generic_ioc`.
 Your Generic ioc has a default ioc instance used for testing.

docs/user/tutorials/ioc_changes.rst

@@ -1,6 +1,10 @@
 Testing Changes to IOC Instances
 ================================
 
+.. Warning::
+
+    This tutorial is out of date and will be updated soon.
+
 .. _ioc_change_types:
 
 Types of Changes

docs/user/tutorials/rtems_ioc.rst

@@ -1,6 +1,10 @@
 RTEMS - Deploying an Example IOC
 ================================
 
+.. Warning::
+
+    This tutorial is out of date and will be updated in November 2023.
+
 The previous tutorials walked through how to create a Generic linux soft
 IOC and how to deploy an IOC instance using that Generic IOC.
 

docs/user/tutorials/rtems_setup.rst

@@ -1,6 +1,10 @@
 RTEMS - Creating a File Server
 ==============================
 
+.. Warning::
+
+    This tutorial is out of date and will be updated in November 2023.
+
 Introduction
 ------------
 

docs/user/tutorials/support_module.rst

@@ -1,6 +1,10 @@
 Working with Support Modules
 =============================
 
+.. Warning::
+
+    This tutorial is out of date and will be updated soon.
+
 TODO: this is currently a stub with some pointers.
 
 TODO: suggest that we will make a new Stream Device that will be a

docs/user/tutorials/test_generic_ioc.rst

@@ -1,6 +1,10 @@
 Testing and Deploying a Generic IOC
 ===================================
 
+.. Warning::
+
+    This tutorial is out of date and will be updated soon.
+
 Continuous Integration
 ----------------------