Docs tidyup. Added image/code styling, reorganised page order

ptsOSL · ptsOSL · commit a3931630a05b · 2025-03-27T11:14:11.000Z
diff --git a/docs/_static/custom.css b/docs/_static/custom.css
@@ -0,0 +1,12 @@
+img[src*='#left'] {
+    float: left;
+}
+
+img[src*='#right'] {
+    float: right;
+}
+
+img[src*='#center'] {
+    display: block;
+    margin: auto;
+}
diff --git a/docs/conf.py b/docs/conf.py
@@ -189,3 +189,12 @@
 # Logo
 html_logo = "images/dls-logo.svg"
 html_favicon = html_logo
+
+# These folders are copied to the documentation's HTML output
+html_static_path = ["_static"]
+
+# These paths are either relative to html_static_path
+# or fully qualified paths (eg. https://...)
+html_css_files = [
+    "custom.css",
+]
diff --git a/docs/explanations.md b/docs/explanations.md
@@ -6,5 +6,6 @@ Explanations of how it works and why it works that way.
 :maxdepth: 1
 :glob:
 
+explanations/implementation_details
 explanations/*
 ```
diff --git a/docs/explanations/feedback_systems.md b/docs/explanations/feedback_systems.md
diff --git a/docs/explanations/implementation_details.md b/docs/explanations/implementation_details.md
diff --git a/docs/tutorials.md b/docs/tutorials.md
@@ -6,5 +6,8 @@ Tutorials for installation and typical usage. New users start here.
 :maxdepth: 1
 :glob:
 
-tutorials/*
+tutorials/installation
+tutorials/overview
+tutorials/atip_example
+tutorials/virtac_example
 ```
diff --git a/docs/tutorials/ATIP_example.md b/docs/tutorials/ATIP_example.md
diff --git a/docs/tutorials/atip_example.md b/docs/tutorials/atip_example.md
@@ -0,0 +1,29 @@
+# ATIP example
+
+## Simmulating accelerator physics using ATIP as a data source for Pytac
+
+Note that you need an AT lattice that is compatible with Pytac. Some are provided
+in ``atip/rings/``, otherwise try running the Matlab function
+``atip/rings/create_lattice_matfile.m`` with an AT lattice loaded.
+
+:::{code-block} python
+
+>>> import pytac
+>>> import atip
+>>> # Load the DIAD lattice from Pytac.
+>>> lat = pytac.load_csv.load('DIAD')
+>>> # Load the AT sim into the Pytac lattice.
+>>> atip.load_sim.load_from_filepath(lat, 'atip/rings/DIAD.mat')
+>>> # Use the sim by default.
+>>> lat.set_default_data_source(pytac.SIM)
+>>> # The initial beam position is zero.
+>>> lat.get_value('x')
+array([0., 0., 0., ..., 0., 0., 0.])
+>>> # Get the first horizontal corrector magnet and set its current to 1A.
+>>> hcor1 = lat.get_elements('HSTR')[0]
+>>> hcor1.set_value('x_kick', 1, units=pytac.ENG)
+>>> # Now the x beam position has changed.
+>>> lat.get_value('x')
+array([0.00240101, 0.00240101, 0.00239875, ..., 0.00240393, 0.00240327,
+        0.00240327])
+:::
diff --git a/docs/tutorials/overview.md b/docs/tutorials/overview.md
@@ -12,7 +12,9 @@ The python implementation of
 [Accelerator Toolbox](<https://github.com/atcollab/at>) (pyAT) is used
 for the simulation.
 
-![How ATIP fits into the combined control structure.](../images/control_structure.png)
+:::sidebar
+<img src="../_images/control_structure.png" alt="How ATIP fits into the combined control structure." width="300px" class="bg-primary" align="right">
+:::
 
 ATIP allows an AT lattice to be fitted into the simulation data source of a
 Pytac lattice. This integrated lattice acts like a normal Pytac lattice, and
diff --git a/docs/tutorials/virtac_example.md b/docs/tutorials/virtac_example.md
@@ -17,33 +17,39 @@ PVs on the live machine.
 
 Run the virtac under the development EPICS port::
 
-    $ export EPICS_CA_SERVER_PORT=6064
-    $ export EPICS_CAS_SERVER_PORT=6064
-    $ export EPICS_CA_REPEATER_PORT=6065
-    $ # at Diamond the above can be set in one go using:    . changeports 6064
-    $ pipenv run virtac
+:::{code-block} bash
+$ export EPICS_CA_SERVER_PORT=6064
+$ export EPICS_CAS_SERVER_PORT=6064
+$ export EPICS_CA_REPEATER_PORT=6065
+$ # at Diamond the above can be set in one go using:    . changeports 6064
+$ pipenv run virtac
+:::
 
 It takes 10 seconds or so to load the interactive console::
 
-    Starting record creation.
-    ~*~*Woah, we're halfway there, Wo-oah...*~*~
-    Finished creating all 2981 records.
-    Starting iocInit
-    ############################################################################
-    ## EPICS 7.0.6.0
-    ## Rev. 7.0.6.99.1.0
-    ############################################################################
-    iocRun: All initialization complete
-    Python 3.7.2 (default, Jan 20 2020, 11:03:41)
-    [GCC 4.8.5 20150623 (Red Hat 4.8.5-39)] on linux
-    Type "help", "copyright", "credits" or "license" for more information.
-    (InteractiveConsole)
-    >>>
+:::{code-block} bash
+Starting record creation.
+~*~*Woah, were halfway there, Wo-oah...*~*~
+Finished creating all 2981 records.
+Starting iocInit
+############################################################################
+## EPICS 7.0.6.0
+## Rev. 7.0.6.99.1.0
+############################################################################
+iocRun: All initialization complete
+Python 3.7.2 (default, Jan 20 2020, 11:03:41)
+[GCC 4.8.5 20150623 (Red Hat 4.8.5-39)] on linux
+Type "help", "copyright", "credits" or "license" for more information.
+(InteractiveConsole)
+>>>
+:::
 
 Leave the server running and in a new terminal update the EPICS port::
 
-    $ export EPICS_CA_SERVER_PORT=6064
-    $ # or:    . changeports 6064
+:::{code-block} bash
+$ export EPICS_CA_SERVER_PORT=6064
+$ # or:    . changeports 6064
+:::
 
 In this new terminal you are then free to address the simulator as you would
 the live machine, either through Pytac or by directly accessing the PVs.
@@ -93,11 +99,15 @@ This is done inside the server console, in the terminal where one you ran
 
    For example disabling SOFB on the first BPM::
 
-       >>> server.set_feedback_record(3, 'enabled', 0)
+:::{code-block} bash
+>>> server.set_feedback_record(3, 'enabled', 0)
+:::
 
    or reducing the beam current::
 
-       >>> server.set_feedback_record(0, 'beam_current', 280)
+:::{code-block} bash
+>>> server.set_feedback_record(0, 'beam_current', 280)
+:::
 
 For further information on working with feedback systems, please refer to
 ``FEEDBACK_SYSTEMS.rst``.
@@ -116,7 +126,9 @@ If none of these is set then the virtual accelerator will default to 'I04'.
 
 For example::
 
-    $ pipenv run virtac I04
-    $ export RINGMODE=I04
-    $ caput SR-CS-RING-01:MODE 3
-    $ # Having none of these set would also start in mode 'I04'.
+:::{code-block} bash
+$ pipenv run virtac I04
+$ export RINGMODE=I04
+$ caput SR-CS-RING-01:MODE 3
+$ # Having none of these set would also start in mode 'I04'.
+:::
