Merge pull request #231 from DiamondLightSource/docs-warnings

Fix docs build. Add docstrings.

Author: GDYendell

docs/conf.py

@@ -89,6 +89,12 @@
     ("py:class", "p4p.nt.NTTable"),
     # Problems in FastCS itself
     ("py:class", "fastcs.transport.epics.pva.pvi_tree._PviSignalInfo"),
+    ("py:class", "fastcs.logging._logging.LogLevel"),
+    ("py:class", "fastcs.logging._graylog.GraylogEndpoint"),
+    ("py:class", "fastcs.logging._graylog.GraylogStaticFields"),
+    ("py:class", "fastcs.logging._graylog.GraylogEnvFields"),
+    ("py:obj", "fastcs.launch.build_controller_api"),
+    ("docutils", "fastcs.demo.controllers.TemperatureControllerSettings"),
     # TypeVar without docstrings still give warnings
     ("py:class", "fastcs.datatypes.T_Numerical"),
     ("py:class", "strawberry.schema.schema.Schema"),
@@ -99,6 +105,8 @@
     (r"py:.*", r"tickit.*"),
 ]
 
+suppress_warnings = ["docutils"]
+
 # Both the class’ and the __init__ method’s docstring are concatenated and
 # inserted into the main body of the autoclass directive
 autoclass_content = "both"

src/fastcs/attribute_io.py

@@ -7,6 +7,17 @@
 
 
 class AttributeIO(Generic[T, AttributeIORefT], Tracer):
+    """Base class for performing IO for an ``Attribute``
+
+    This class should be inherited to implement reading and writing values from
+    ``Attributes`` via some API. For read, ``Attribute``s implement the ``update``
+    method and for write, ``Attribute`` implement the ``send`` method.
+
+    Concrete implementations of this class must be parameterised with a specific
+    ``AttributeIORef`` that defines exactly what part of the API the ``Attribute``
+    corresponds to. See the docstring for ``AttributeIORef`` for more information.
+    """
+
     ref_type = AttributeIORef
 
     def __init_subclass__(cls) -> None:

src/fastcs/attribute_io_ref.py

@@ -5,6 +5,15 @@
 
 @dataclass(kw_only=True)
 class AttributeIORef:
+    """Base for references to define IO for an ``Attribute`` over an API.
+
+    This object acts as a specification of the API that its corresponding
+    ``AttributeIO`` should access for a given ``Attribute``. The fields necessary to
+    distinguish between different ``Attributes`` is an implementation detail of the IO,
+    but some examples are a string to send over a TCP port, or URI within an HTTP
+    server.
+    """
+
     update_period: float | None = None
 
 

src/fastcs/logging/__init__.py

@@ -40,14 +40,12 @@
 
     logger = _logger.bind(logger_name=__name__)
 
-
 or to create a class logger with its name
 
 .. code-block:: python
 
     self.logger = _logger.bind(logger_name=__class__.__name__)
 
-
 As standard ``loguru`` supports ``trace`` level monitoring, but it should not be used in
 fastcs. Instead there is a ``Tracer`` class for verbose logging with fine-grained
 controls that can be enabled by the user at runtime.

src/fastcs/tracer.py

@@ -20,6 +20,7 @@ class Tracer:
 
     Example usage:
     .. code-block:: python
+
         controller.ramp_rate.enable_tracing()
         controller.ramp_rate.disable_tracing()
         controller.connection.enable_tracing()