From b9fe4361e0e360c4e37fa746cfd2eafc2d18e7c2 Mon Sep 17 00:00:00 2001
From: Jan David Mol <mol@astron.nl>
Date: Thu, 7 Oct 2021 12:16:54 +0200
Subject: [PATCH] L2SS-434: ` -> `` for literal quotes.
---
docs/source/control.rst | 2 +-
docs/source/devices/devices.rst | 10 +++++-----
docs/source/devices/using.rst | 26 +++++++++++++-------------
docs/source/installation.rst | 6 +++---
docs/source/logs.rst | 6 +++---
docs/source/monitoring.rst | 8 ++++----
6 files changed, 29 insertions(+), 29 deletions(-)
diff --git a/docs/source/control.rst b/docs/source/control.rst
index 9fa847bf6..c9500c3c1 100644
--- a/docs/source/control.rst
+++ b/docs/source/control.rst
@@ -12,7 +12,7 @@ The notebooks provide some predefined variables, so you don't have to look them
.. literalinclude:: ../../docker-compose/jupyter/ipython-profiles/stationcontrol-jupyter/startup/01-devices.py
-Note: the Jupyter notebooks use enhancements from the `itango` suite, which provide tab completions, but also the `Device` alias for `DeviceProxy` as was used in the Python examples in the next section.
+Note: the Jupyter notebooks use enhancements from the ``itango`` suite, which provide tab completions, but also the ``Device`` alias for ``DeviceProxy`` as was used in the Python examples in the next section.
For example, you can start a new *Station Control* notebook (File->New Notebook->StationControl), and access these devices:
diff --git a/docs/source/devices/devices.rst b/docs/source/devices/devices.rst
index 7cc6c7b90..228f03f41 100644
--- a/docs/source/devices/devices.rst
+++ b/docs/source/devices/devices.rst
@@ -4,15 +4,15 @@ Devices
RECV
----------
-The `recv == Device("LTS/RECV/1")` device controls the RCUs, the LBA antennas, and HBA tiles. Central to its operation are the masks:
+The ``recv == Device("LTS/RECV/1")`` device controls the RCUs, the LBA antennas, and HBA tiles. Central to its operation are the masks:
-- The `RCU_mask_RW` attribute is an array of `bool[N_RCUs]`. It controls which RCUs will actually be configured, when fields referring to RCUs are set. Any RCU for which the mask is False will not be configured when RCU control points are set.
-- The `Ant_mask_RW` attribute is an array of `bool[N_RCUs][N_Antennas_per_RCU]`. It controls which antennas will actually be configured, when fields referring to antennas are set. Any antenna for which the mask is False will not be configured when antenna control points are set.
+- The ``RCU_mask_RW`` attribute is an array of ``bool[N_RCUs]``. It controls which RCUs will actually be configured, when fields referring to RCUs are set. Any RCU for which the mask is False will not be configured when RCU control points are set.
+- The ``Ant_mask_RW`` attribute is an array of ``bool[N_RCUs][N_Antennas_per_RCU]``. It controls which antennas will actually be configured, when fields referring to antennas are set. Any antenna for which the mask is False will not be configured when antenna control points are set.
-Typically, `N_RCUs == 32`, and `N_Antennas_per_RCU == 3`.
+Typically, ``N_RCUs == 32``, and ``N_Antennas_per_RCU == 3``.
SST and XST
-----------
-The `sst == Device("LTS/SST/1")` and `xst == Device("LTS/XST/1")` devices manages the SSTs (subband statistics) and XSTs (crosslet statistics), respectively, that are emitted by the Uniboards in SDP. By default, each device configures the statistics to be streamed to itself (the device), from where the user can obtain them.
+The ``sst == Device("LTS/SST/1")`` and ``xst == Device("LTS/XST/1")`` devices manages the SSTs (subband statistics) and XSTs (crosslet statistics), respectively, that are emitted by the Uniboards in SDP. By default, each device configures the statistics to be streamed to itself (the device), from where the user can obtain them.
diff --git a/docs/source/devices/using.rst b/docs/source/devices/using.rst
index acc9e12ef..afc753773 100644
--- a/docs/source/devices/using.rst
+++ b/docs/source/devices/using.rst
@@ -9,32 +9,32 @@ The station exposes *devices*, each of which is a remote software object that ma
- It exposes *read-write attributes*, that allow controlling the functionality of the device, or the hardware it represents,
- It exposes *properties*, which are fixed configuration parameters (such as port numbers and timeouts).
-To access a device, one creates a `Device` object. For example::
+To access a device, one creates a ``Device`` object. For example::
device = Device("LTS/RECV/1")
States
------------
-The state of a device is then queried with `device.state()`. Each device can be in one of the following states:
+The state of a device is then queried with ``device.state()``. Each device can be in one of the following states:
-- `DevState.OFF`: The device is not operating,
-- `DevState.INIT`: The device is being initialised,
-- `DevState.STANDBY`: The device is initialised and ready to be configured further,
-- `DevState.ON`: The device is operational.
-- `DevState.FAULT`: The device is malfunctioning. Functionality cannot be counted on.
-- The `device.state()` function can throw an error, if the device cannot be reached at all. For example, because it's docker container has not been started.
+- ``DevState.OFF``: The device is not operating,
+- ``DevState.INIT``: The device is being initialised,
+- ``DevState.STANDBY``: The device is initialised and ready to be configured further,
+- ``DevState.ON``: The device is operational.
+- ``DevState.FAULT``: The device is malfunctioning. Functionality cannot be counted on.
+- The ``device.state()`` function can throw an error, if the device cannot be reached at all. For example, because it's docker container has not been started.
Each device provides the following functions to change state:
-- `off()`: Turn the device `OFF` from any state.
-- `initialise()`: Initialise the device from the `OFF` state, to bring it to the `STANDBY` state.
-- `on()`: Mark the device as operational, from the `STANDBY` state, bringing it to `ON`.
+- ``off()``: Turn the device ``OFF`` from any state.
+- ``initialise()``: Initialise the device from the ``OFF`` state, to bring it to the ``STANDBY`` state.
+- ``on()``: Mark the device as operational, from the ``STANDBY`` state, bringing it to ``ON``.
Attributes
------------
-The device can be operated in `ON` state, where it exposes *attributes* and *commands*. The attributes can be accessed as python properties, for example::
+The device can be operated in ``ON`` state, where it exposes *attributes* and *commands*. The attributes can be accessed as python properties, for example::
recv = Device("LTS/RECV/1")
@@ -44,4 +44,4 @@ The device can be operated in `ON` state, where it exposes *attributes* and *com
# retrieve the status of all LED0s
print(recv.RCU_LED0_R)
-The attributes with an `_R` suffix are monitoring points, reflecting the state of the hardware, and are thus read-only. The attributes with an `_RW` suffix are control points, reflecting the desired state of the hardware. They are read-write, where writing requests the hardware to set the specified value, and reading returns the last requested value.
+The attributes with an ``_R`` suffix are monitoring points, reflecting the state of the hardware, and are thus read-only. The attributes with an ``_RW`` suffix are control points, reflecting the desired state of the hardware. They are read-write, where writing requests the hardware to set the specified value, and reading returns the last requested value.
diff --git a/docs/source/installation.rst b/docs/source/installation.rst
index 51e534f31..4643aaa3f 100644
--- a/docs/source/installation.rst
+++ b/docs/source/installation.rst
@@ -36,10 +36,10 @@ and make sure they are all up and running::
You should see the following state:
-- Containers `astor`, `hdbpp-viewer`, `jive`, `log-viewer` and `pogo` will have State `Exit 1`. These are containers that are interactive X11 tools, and not needed for now,
-- Other containers have either State `Up` or `Exit 0`.
+- Containers ``astor``, ``hdbpp-viewer``, ``jive``, ``log-viewer`` and ``pogo`` will have State ``Exit 1``. These are containers that are interactive X11 tools, and not needed for now,
+- Other containers have either State ``Up`` or ``Exit 0``.
-If not, you can inspect why with `docker logs <container>`. Note that the containers will automatically be restarted on failure, and also if you reboot. Stop them explicitly to bring them down (`make stop <container>`).
+If not, you can inspect why with ``docker logs <container>``. Note that the containers will automatically be restarted on failure, and also if you reboot. Stop them explicitly to bring them down (``make stop <container>``).
Post-boot Initialisation
---------------------------
diff --git a/docs/source/logs.rst b/docs/source/logs.rst
index f0a92a386..fd6b9735a 100644
--- a/docs/source/logs.rst
+++ b/docs/source/logs.rst
@@ -1,7 +1,7 @@
Logs
==================
-The devices, and the docker containers in general, produce logging output. The easiest way to access the logs of a specific container is to ask docker directly. For example, to access and follow the most recent logs of the `device-sdp` container, execute on the host::
+The devices, and the docker containers in general, produce logging output. The easiest way to access the logs of a specific container is to ask docker directly. For example, to access and follow the most recent logs of the ``device-sdp`` container, execute on the host::
docker logs -n 100 -f device-sdp
@@ -15,13 +15,13 @@ To monitor the logs remotely, or to browse older logs, use the *ELK stack* that
- Logs of all devices,
- Logs of the Jupyter notebook server.
-If you browse to the ELK stack (actually, it is Kibana providing the GUI), your go-to is the *Discover* view at http://localhost:5601/app/discover. There, you can construct (and save, load) a dashboard that provides a custom view of the logs, based on the *index pattern* `logstash-*`. There is a lot to take in, and there are excellent Kibana tutorials on the web.
+If you browse to the ELK stack (actually, it is Kibana providing the GUI), your go-to is the *Discover* view at http://localhost:5601/app/discover. There, you can construct (and save, load) a dashboard that provides a custom view of the logs, based on the *index pattern* ``logstash-*``. There is a lot to take in, and there are excellent Kibana tutorials on the web.
To get going, use for example `this dashboard <http://localhost:5601/app/discover#/?_g=(filters:!(),refreshInterval:(pause:!t,value:0),time:(from:now-60m,to:now))&_a=(columns:!(extra.tango_device,level,message),filters:!(),index:'1e8ca200-1be0-11ec-a85f-b97e4206c18b',interval:auto,query:(language:kuery,query:''),sort:!())>`_, which shows the logs of the last hour, with some useful columns added to the default timestamp and message columns. Expand the time range if no logs appear, to look further back. You should see something like:
.. image:: elk_last_hour.png
-ELK allows you to filter, edit the columns, and a lot more. We enrich the log entries with several extra fields, for example the device that generated it, and stack traces if available. Click on the `>` before a log entry and the information expands, showing for example:
+ELK allows you to filter, edit the columns, and a lot more. We enrich the log entries with several extra fields, for example the device that generated it, and stack traces if available. Click on the ``>`` before a log entry and the information expands, showing for example:
.. image:: elk_log_fields.png
diff --git a/docs/source/monitoring.rst b/docs/source/monitoring.rst
index 5c5c30c52..1fbcf81d7 100644
--- a/docs/source/monitoring.rst
+++ b/docs/source/monitoring.rst
@@ -1,7 +1,7 @@
Monitoring GUIs
========================
-Each device exposes a list of monitoring points as attributes with the `_R` prefix. These can be accessed interactively from a controle console (such as Jupyter), but that will not scale.
+Each device exposes a list of monitoring points as attributes with the ``_R`` prefix. These can be accessed interactively from a controle console (such as Jupyter), but that will not scale.
Grafana
------------------------
@@ -42,7 +42,7 @@ Prometheus stores attributes in the following format::
type="float",
x="00", y="0"}
-The above describes a single data point and its labels. The primary identifying labels are `device` and `name`. Each point furthermore has a value (integer) and a timestamp. The following transformations take place:
+The above describes a single data point and its labels. The primary identifying labels are ``device`` and ``name``. Each point furthermore has a value (integer) and a timestamp. The following transformations take place:
-- For 1D and 2D attributes, each array element is its own monitoring point, with `x` and `y` labels describing the indices. The labels `dim_x` and `dim_y` describe the array dimensionality,
-- Attributes with string values get a `str_value` label describing their value.
+- For 1D and 2D attributes, each array element is its own monitoring point, with ``x`` and ``y`` labels describing the indices. The labels ``dim_x`` and ``dim_y`` describe the array dimensionality,
+- Attributes with string values get a ``str_value`` label describing their value.
--
GitLab