new index format

Author: gilesknap

README.rst

@@ -55,9 +55,13 @@ Kubernetes worker node.
 - The entire definition of the the example P45 beamline is held in this
   github organization:
 
-  - Helm Charts: https://github.com/orgs/epics-containers/packages
-  - IOC Images: https://github.com/orgs/epics-containers/packages
-  - BL45P IOC sources: https://github.com/epics-containers/bl45p
+  - Helm Charts and IOC Images:
+
+    - https://github.com/orgs/epics-containers/packages
+
+  - BL45P IOC sources:
+
+    - https://github.com/epics-containers/bl45p
 
 ..
     Anything below this line is used when viewing README.rst and will be replaced

docs/explanations/whats_in.rst

@@ -16,9 +16,9 @@ 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**: 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.
+The tutorial `create_beamline` supplies a demo beamline
+with an IOC that is based purely on a simulated Area Detector
+so that anyone can experiment with Kubernetes for EPICS IOCs.
 
 
 Production generic IOCs

docs/index.rst

@@ -4,45 +4,41 @@
 How the documentation is structured
 ===================================
 
+Documentation is split into four categories, accessible from links in the side-bar.
+
 .. rst-class:: columns
 
-:ref:`tutorials`
-~~~~~~~~~~~~~~~~
+Tutorials
+~~~~~~~~~
 
 Tutorials for setting up a test cluster, and deploying an IOC.
 
 .. rst-class:: columns
 
-:ref:`explanations`
-~~~~~~~~~~~~~~~~~~~
+Explanations
+~~~~~~~~~~~~
 
 Explanation of the principal ideas for deploying IOCs in Kubernetes.
 
 .. rst-class:: columns
 
-:ref:`how-to`
+How-to Guides
 ~~~~~~~~~~~~~
 
 Practical step-by-step guides for the more experienced user.
 
 .. rst-class:: columns
 
-:ref:`reference`
-~~~~~~~~~~~~~~~~
+Reference
+~~~~~~~~~
 
 Technical reference material.
 
 .. rst-class:: endcolumns
 
-About the documentation
-~~~~~~~~~~~~~~~~~~~~~~~
-
-`Why is the documentation structured this way? <https://documentation.divio.com>`_
-
 .. toctree::
     :caption: Tutorials
-    :name: tutorials
-    :maxdepth: 1
+    :hidden:
 
     tutorials/setup_k8s
     tutorials/useful_k8s
@@ -52,8 +48,7 @@ About the documentation
 
 .. toctree::
     :caption: Explanations
-    :name: explanations
-    :maxdepth: 1
+    :hidden:
 
     explanations/introduction
     explanations/whats_in
@@ -62,8 +57,7 @@ About the documentation
 
 .. toctree::
     :caption: How-to Guides
-    :name: how-to
-    :maxdepth: 1
+    :hidden:
 
     how-to/add_ioc
     how-to/create_ioc
@@ -74,10 +68,15 @@ About the documentation
 
 .. toctree::
     :caption: Reference
-    :name: reference
-    :maxdepth: 1
+    :hidden:
 
     reference/faq
     reference/cli
     reference/contributing
 
+.. rst-class:: endcolumns
+
+About the documentation
+~~~~~~~~~~~~~~~~~~~~~~~
+
+`Why is the documentation structured this way? <https://documentation.divio.com>`_

docs/tutorials/create_beamline.rst

@@ -1,3 +1,5 @@
+.. _create_beamline:
+
 Create a beamline repository
 ============================