improve docs

Author: Tom-Willemsen

doc/_static/css/custom.css

@@ -5,3 +5,12 @@ a:hover {
 .wy-menu-vertical p.caption {
     color: #d2b48c;
 }
+
+.sphinx-codeautolink-a{
+    border-bottom-color: #d2b48c;
+    border-bottom-style: solid;
+    border-bottom-width: 1px;
+}
+.sphinx-codeautolink-a:hover{
+    color: #888888;
+}

doc/conf.py

@@ -45,6 +45,8 @@
     "sphinx.ext.viewcode",
     # Mermaid diagrams
     "sphinxcontrib.mermaid",
+    # Documentation links in code blocks
+    "sphinx_codeautolink",
 ]
 mermaid_d3_zoom = True
 napoleon_google_docstring = True
@@ -73,6 +75,7 @@
 html_css_files = [
     "css/custom.css",
 ]
+html_logo = "logo.svg"
 
 autoclass_content = "init"
 myst_heading_anchors = 7

doc/contributing.md

@@ -16,7 +16,8 @@ You can also use `uv pip install -e .[dev]` if you have the [`uv`](https://docs.
 
 ## Linting
 
-Linting is performed by `ruff` (formatting & linting) and `pyright` (type-checking).
+Linting is performed by [ruff](https://docs.astral.sh/ruff/) (formatting & linting) and
+[pyright](https://github.com/microsoft/pyright) (type-checking).
 
 ```shell
 ruff format
@@ -26,8 +27,8 @@ pyright
 
 ## Documentation
 
-Documentation is built using `sphinx`. To get a local development build of the docs, use
-`sphinx-autobuild doc _build --watch src`.
+Documentation is built using [sphinx](https://www.sphinx-doc.org/en/master/).
+To get a local development build of the docs, use `sphinx-autobuild doc _build --watch src`.
 
 Spell checking is run automatically in CI - if a word is correctly spelt but the spellchecker flags it,
 add the word to `doc/spelling_wordlist.txt`.

doc/logo.svg

@@ -24,6 +24,7 @@ raw mode; set {py:obj}`SecopQuirks.raw_struct <fastcs_secop.SecopQuirks.raw_stru
 {py:obj}`SecopQuirks.raw_matrix <fastcs_secop.SecopQuirks.raw_matrix>` is also recommended, as only 1-D matrices are
 supported by CA.
 
+{#example_ca_ioc}
 ## Example CA IOC
 
 :::python

doc/transports/epics_ca.md

@@ -27,6 +27,7 @@ Other data types can only be read or written in 'raw' mode.
 SECoP modules can be found under the top-level PVI structure, while SECoP accessibles can be found under
 `module_name:PVI`. This means that the IOC is self-describing to downstream clients.
 
+{#example_pva_ioc}
 ## Example PVA IOC
 
 :::python

doc/transports/epics_pva.md

@@ -37,6 +37,7 @@ doc = [
   "sphinx_rtd_theme", 
   "myst_parser",
   "sphinx-autobuild",
+  "sphinx-codeautolink",
   "sphinxcontrib-mermaid",
   "sphinxcontrib-spelling",
 ]

pyproject.toml

@@ -37,6 +37,9 @@ def __init__(
     ) -> None:
         """Subcontroller for a SECoP command.
 
+        This class is automatically added as a subcontroller by
+        :py:obj:`SecopModuleController` for command-type parameters.
+
         Args:
             connection: The connection to use.
             module_name: The module in which this command is defined.
@@ -134,8 +137,8 @@ def __init__(
     ) -> None:
         """FastCS controller for a SECoP module.
 
-        Instances of this class are added as subcontrollers by
-        :py:obj:`SecopController`.
+        This class is automatically added as a subcontroller by
+        :py:obj:`SecopController` for each present SECoP module.
 
         Args:
             connection: The connection to use.
@@ -217,6 +220,29 @@ class SecopController(Controller):
     def __init__(self, settings: IPConnectionSettings, quirks: SecopQuirks | None = None) -> None:
         """FastCS Controller for a SECoP node.
 
+        The intended usage is via :py:obj:`fastcs.control_system.FastCS`:
+
+        .. code-block:: python
+
+            from fastcs_secop import SecopController, SecopQuirks
+            from fastcs.control_system import FastCS
+
+            controller = SecopController(
+                settings=IPConnectionSettings(ip="127.0.0.1", port=1234),
+                quirks=SecopQuirks(...),
+            )
+
+            transports = [...]
+
+            fastcs = FastCS(
+                controller,
+                transports,
+            )
+            fastcs.run()
+
+        See Also:
+            :ref:`example_ca_ioc` and :ref:`example_pva_ioc` for examples of full configurations
+
         Args:
             settings: The communication settings (e.g. IP address, port) at which
                 the SECoP node is reachable.

src/fastcs_secop/_controllers.py

@@ -212,6 +212,7 @@ async def send(self, attr: AttrW[T, SecopAttributeIORef], value: T) -> None:
                 encoded_value,
             )
             # Ugly, but I can't find a public alternative...
+            # https://github.com/DiamondLightSource/FastCS/pull/292
             await attr._call_sync_setpoint_callbacks(value)  # noqa: SLF001
         except ConnectionError:
             # Reconnect will be attempted in a periodic scan task
@@ -223,8 +224,8 @@ async def send(self, attr: AttrW[T, SecopAttributeIORef], value: T) -> None:
 class SecopRawAttributeIO(AttributeIO[str, SecopRawAttributeIORef]):
     """Raw IO for a SECoP parameter of any type other than 'command'.
 
-    For "raw" IO, no serialization/deserialization is performed. All values are transmitted
-    to/from FastCS as strings. It is up to the client to interpret those strings correctly.
+    For "raw" IO, all values are transmitted to/from FastCS as strings.
+    It is up to the client to interpret those strings correctly.
 
     This is intended as a fallback mode for transports which cannot represent complex
     data types.
@@ -262,6 +263,7 @@ async def send(self, attr: AttrW[str, SecopRawAttributeIORef], value: str) -> No
                 value,
             )
             # Ugly, but I can't find a public alternative...
+            # https://github.com/DiamondLightSource/FastCS/pull/292
             await attr._call_sync_setpoint_callbacks(value)  # noqa: SLF001
         except ConnectionError:
             # Reconnect will be attempted in a periodic scan task

src/fastcs_secop/_io.py

@@ -28,26 +28,40 @@ class SecopQuirks:
     """Skip creating any listed ``(module_name, accessible_name)`` tuples."""
 
     raw_accessibles: Collection[tuple[str, str]] = field(default_factory=list)
-    """Create any listed ``(module_name, accessible_name)`` tuples in 'raw' mode."""
+    """Create any listed ``(module_name, accessible_name)`` tuples in raw mode.
+
+    JSON for the specified accessibles will be treated as strings.
+    """
 
     raw_array: bool = False
     """If the accessible has an array type, read it in raw mode.
+
+    JSON values for any array-type accessible will be treated as strings.
     """
 
     raw_matrix: bool = False
     """If the accessible has a matrix type, read it in raw mode.
+
+    JSON values for any matrix-type accessible will be treated as strings.
+
+    This is useful for transports which cannot represent arbitrary N-dimensional
+    arrays.
     """
 
     raw_tuple: bool = False
     """If the accessible has a tuple type, read it in raw mode.
 
+    JSON values for any tuple-type accessible will be treated as strings.
+
     This is useful for transports which do not support the FastCS
     :py:obj:`~fastcs.datatypes.table.Table` type.
     """
 
     raw_struct: bool = False
     """If the accessible has a struct type, read it in raw mode.
 
+    JSON values for any struct-type accessible will be treated as strings.
+
     This is useful for transports which do not support the FastCS
     :py:obj:`~fastcs.datatypes.table.Table` type.
     """