tidy explanations and readme

Author: gilesknap

CONTRIBUTING.rst

@@ -1,13 +1,18 @@
 Contributing
 ============
 
-Contributions and issues are most welcome! All issues and pull requests for
+Contributions and issues are most welcome!
+
+For general comments and ideas please use the `Wiki`_
+
+All issues and pull requests for
 the documentation or for the ideas expressed in the epics-containers
-organization are handled through github on the `k8s-epics-docs repository`_.
+organization are handled in the `epics-containers.github.io repository`_.
 
-Report issues for generic iocs etc. in their own repos.
+Please report issues for generic iocs etc. in their own source repos.
 
-.. _k8s-epics-docs repository: https://github.com/epics-containers/epics-containers.github.io/issues
+.. _Wiki: https://github.com/epics-containers/k8s-epics-utils/wiki
+.. _epics-containers.github.io repository: https://github.com/epics-containers/epics-containers.github.io/issues
 
 Running the tests
 -----------------

README.rst

@@ -3,13 +3,17 @@ epics-containers
 
 |docs_ci| |license|
 
-epics-containers is an experimental GitHub organizaion to try out ideas
+epics-containers is an experimental GitHub organization to try out ideas
 for managing EPICS IOCs in a Kubernetes cluster.
 
+Please contribute with comments and suggestions in the wiki or issues pages:
+
 ============== ==============================================================
-Organization   https://github.com/epics-containers
 Documentation  https://epics-containers.github.io
+Wiki           https://github.com/epics-containers/epics-containers.github.io/wiki
+Issues         https://github.com/epics-containers/epics-containers.github.io/issues
 Docs Source    https://github.com/epics-containers/epics-containers.github.io
+Organization   https://github.com/epics-containers
 ============== ==============================================================
 
 
@@ -22,15 +26,21 @@ Docs Source    https://github.com/epics-containers/epics-containers.github.io
     :alt: Apache License
 
 
-**TODO** include a nice diagram and brief overview
+Overview
+========
 
+.. include:: overview.rst
 
-*Placeholder:*
+This diagram shows how the assets combine to create a running IOC on a
+Kubernetes worker node.
 
 .. image:: images/example.png
     :width: 1500px
     :align: center
 
+- The Helm Chart defines an IOC instance: IMAGE + STARTUP SCRIPT + K8S DEPLOYMENT​
+- The entire definition of the P45 beamline is held in https://github.com/orgs/epics-containers/packages
+
 ..
     Anything below this line is used when viewing README.rst and will be replaced
     when included in index.rst

docs/explanations/introduction.rst

@@ -4,26 +4,7 @@ Essential Concepts
 Overview
 --------
 
-Kubernetes for EPICS IOCs applies modern industry standards to the management
-of IOCs. The same standards used by the majority of micro-service and
-SOA applications today.
-
-There are 5 themes to this strategy:
-
-:Containers​:
-  Package IOC software and execute it in a lightweight virtual environment​.
-
-:Kubernetes​:
-  Centrally orchestrate all IOCs at a facility.
-
-:Helm Charts​:
-  Deploy IOCs into Kubernetes with version management​.
-
-:Repositories​:
-  Source, container and helm repositories manage all of the above assets. No shared file systems required.​
-
-:Continuous Integration / Deployment​:
-  Source repositories automatically build assets from source when it is updated. And potentially deploy to Kubernetes.​
+.. include:: overview.rst
 
 See below for more detail on each of these.
 
@@ -146,7 +127,7 @@ The 3 classes of repository are as follows:
 :Source Repository:
   - Holds the source code but also provides the
     Continuous Integration actions for testing, building and publishing to
-    the following 2 repositories. These have been tested:
+    the image / helm repositories. These have been tested:
 
     - github
     - gitlab (on prem)
@@ -201,7 +182,7 @@ There are these types of CI:
 
 Scope
 -----
-This project currently targets the low hanging fruit of x86_64 Linux Soft
+This project initially targets the low hanging fruit of x86_64 Linux Soft
 IOCs only.
 
 Other linux architectures could be added to the Kubernetes cluster.
@@ -213,6 +194,8 @@ because windows containers require a windows host.
 Hard IOCs will not be supported in their current form. Perhaps there is a
 future possibility of turning hard IOCs remote devices.
 
+Note that OPI is also out of scope for this initial phase. See
+`no_opi`
 
 Additional Tools
 ----------------
@@ -222,10 +205,13 @@ k8s-epics-utils
 The project k9s-epics utils contains a script to add simple command
 line functions for deploying and monitoring IOCs.
 
+See `CLI` for details.
+
 It also provides a Dockerfile for building a personal developer image
 allowing a developer to work on support modules or IOCs anywhere.
 
-See the repository documentation (TODO)
+TODO provide documentation for the developer image.
+
 
 Ibek
 ~~~~

docs/explanations/kubernetes_cluster.rst

@@ -4,7 +4,7 @@ Kubernetes Cluster Config
 Cluster Options
 ---------------
 
-Three cluster topology approaches were considered for this project.
+Three cluster topologies were considered for this project.
 
 :Cluster per beamline:
   This could be as simple as
@@ -35,6 +35,7 @@ Three cluster topology approaches were considered for this project.
   how to achieve this.
 
 
+.. _argus:
 
 DLS Argus Cluster
 -----------------

docs/explanations/overview.rst

@@ -0,0 +1 @@
+../../overview.rst

docs/explanations/strategy.rst

@@ -10,13 +10,13 @@ By way of example we will include a full implementation of the
 test beamline BL45P at Diamond Light Source.
 
 The benefit of this is that it will be live and constantly kept up to date with
-the latest developments. Also proven to work (**TODO** ref documentation on the
-DLS beamline Kubernetes infrastructure)
+the latest developments. Also proven to work, see `argus` for details of the
+DLS cluster which hosts this beamline.
 
 The downside is that it will only serve as an example; those without access
 to the beamline will not be able to run the code without getting errors.
 
-**TODO**: supply a demo beamline that is based purely on simulated devices
+**TODO**: we will supply a demo beamline that is based purely on simulated devices
 so that anyone can experiment with Kubernetes for EPICS IOCs, this will be
 used in the tutorials to walk through deployment.
 
@@ -75,7 +75,7 @@ e.g.
 :epics:
     this prefix is for images that are nodes in the network of
     image dependencies.
-    e.g. epics-base, epics-adcore
+    e.g. epics-base, epics-areadetector
 
 :iocs:
     this prefix is for images that are leaves in the network of

docs/explanations/whats_in.rst

@@ -2,7 +2,7 @@
     :end-before: when included in index.rst
 
 How the documentation is structured
------------------------------------
+===================================
 
 .. rst-class:: columns
 
@@ -55,7 +55,6 @@ About the documentation
     :maxdepth: 1
 
     explanations/introduction
-    explanations/strategy
     explanations/whats_in
     explanations/net_protocols
     explanations/kubernetes_cluster

docs/index.rst

@@ -0,0 +1 @@
+../overview.rst

docs/overview.rst

@@ -1,6 +1,8 @@
 Frequently Asked Questions
 ==========================
 
+.. _no_opi:
+
 Why no mention of Operator Interfaces?
 --------------------------------------
 OPI was out of scope for the proof of concept. That is because we