Lint RST in docstrings

sphinx-autodoc2 gives difficult-to-follow errors that don't easily show where in the source they come from.
I've set up flake8 to lint the docstrings, and fixed the errors. I've also fixed my links, which used incorrect syntax for `:ref:` links.

I may try out sphinx.ext.autodoc instead - this imports the module, but might be more reliable.

Author: rwb27

NOTES.md

@@ -60,6 +60,8 @@ switched to using `pydoclint` directly, and configured it in `pyproject.toml`. I
   - Example code in the descriptor may want a doctest in due course.
   - Could do with example code showing how it works in a simple camera?
 * `server`: could do with some more specific exceptions.
+  - `__init__:80` does this need to be a global? I think it might work without, and flake8 complains.
+    I've silenced it at the import and also the global line.
 * `server.cli`: need a model for config.
 * `thing_description`:
   - Custom exception for `recursion_limit`

dev-requirements.txt

@@ -1,5 +1,7 @@
 # This file was autogenerated by uv via the following command:
 #    uv pip compile --extra dev pyproject.toml --output-file dev-requirements.txt
+alabaster==0.7.16
+    # via sphinx
 annotated-types==0.7.0
     # via pydantic
 anyio==4.8.0
@@ -12,10 +14,15 @@ attrs==25.1.0
     # via
     #   jsonschema
     #   referencing
+babel==2.17.0
+    # via sphinx
 certifi==2025.1.31
     # via
     #   httpcore
     #   httpx
+    #   requests
+charset-normalizer==3.4.2
+    # via requests
 click==8.1.8
     # via
     #   pydoclint
@@ -26,19 +33,40 @@ colorama==0.4.6
     # via
     #   click
     #   pytest
+    #   sphinx
     #   uvicorn
 coverage==7.6.12
     # via pytest-cov
 dnspython==2.7.0
     # via email-validator
 docstring-parser-fork==0.0.12
     # via pydoclint
+docutils==0.20.1
+    # via
+    #   restructuredtext-lint
+    #   sphinx
+    #   sphinx-rtd-theme
 email-validator==2.2.0
     # via fastapi
 fastapi==0.115.11
     # via labthings-fastapi (pyproject.toml)
 fastapi-cli==0.0.7
     # via fastapi
+flake8==7.3.0
+    # via
+    #   labthings-fastapi (pyproject.toml)
+    #   flake8-docstrings
+    #   flake8-pyproject
+    #   flake8-rst
+    #   flake8-rst-docstrings
+flake8-docstrings==1.7.0
+    # via labthings-fastapi (pyproject.toml)
+flake8-pyproject==1.2.3
+    # via labthings-fastapi (pyproject.toml)
+flake8-rst==0.8.0
+    # via labthings-fastapi (pyproject.toml)
+flake8-rst-docstrings==0.3.1
+    # via labthings-fastapi (pyproject.toml)
 h11==0.14.0
     # via
     #   httpcore
@@ -56,14 +84,19 @@ idna==3.10
     #   anyio
     #   email-validator
     #   httpx
+    #   requests
 ifaddr==0.2.0
     # via zeroconf
+imagesize==1.4.1
+    # via sphinx
 iniconfig==2.0.0
     # via pytest
 itsdangerous==2.2.0
     # via fastapi
 jinja2==3.1.6
-    # via fastapi
+    # via
+    #   fastapi
+    #   sphinx
 jsonschema==4.23.0
     # via labthings-fastapi (pyproject.toml)
 jsonschema-specifications==2024.10.1
@@ -72,6 +105,8 @@ markdown-it-py==3.0.0
     # via rich
 markupsafe==3.0.2
     # via jinja2
+mccabe==0.7.0
+    # via flake8
 mdurl==0.1.2
     # via markdown-it-py
 mypy==1.15.0
@@ -83,11 +118,15 @@ numpy==2.2.3
 orjson==3.10.15
     # via fastapi
 packaging==24.2
-    # via pytest
+    # via
+    #   pytest
+    #   sphinx
 pillow==11.3.0
     # via labthings-fastapi (pyproject.toml)
 pluggy==1.5.0
     # via pytest
+pycodestyle==2.14.0
+    # via flake8
 pydantic==2.10.6
     # via
     #   labthings-fastapi (pyproject.toml)
@@ -102,8 +141,15 @@ pydantic-settings==2.8.1
     # via fastapi
 pydoclint==0.6.6
     # via labthings-fastapi (pyproject.toml)
+pydocstyle==6.3.0
+    # via flake8-docstrings
+pyflakes==3.4.0
+    # via flake8
 pygments==2.19.1
-    # via rich
+    # via
+    #   flake8-rst-docstrings
+    #   rich
+    #   sphinx
 pytest==7.4.4
     # via
     #   labthings-fastapi (pyproject.toml)
@@ -125,6 +171,10 @@ referencing==0.36.2
     #   jsonschema
     #   jsonschema-specifications
     #   types-jsonschema
+requests==2.32.4
+    # via sphinx
+restructuredtext-lint==1.4.0
+    # via flake8-rst-docstrings
 rich==13.9.4
     # via
     #   rich-toolkit
@@ -141,6 +191,31 @@ shellingham==1.5.4
     # via typer
 sniffio==1.3.1
     # via anyio
+snowballstemmer==3.0.1
+    # via
+    #   pydocstyle
+    #   sphinx
+sphinx==7.4.7
+    # via
+    #   labthings-fastapi (pyproject.toml)
+    #   sphinx-rtd-theme
+    #   sphinxcontrib-jquery
+sphinx-rtd-theme==2.0.0
+    # via labthings-fastapi (pyproject.toml)
+sphinxcontrib-applehelp==2.0.0
+    # via sphinx
+sphinxcontrib-devhelp==2.0.0
+    # via sphinx
+sphinxcontrib-htmlhelp==2.1.0
+    # via sphinx
+sphinxcontrib-jquery==4.1
+    # via sphinx-rtd-theme
+sphinxcontrib-jsmath==1.0.1
+    # via sphinx
+sphinxcontrib-qthelp==2.0.0
+    # via sphinx
+sphinxcontrib-serializinghtml==2.0.0
+    # via sphinx
 starlette==0.46.0
     # via fastapi
 typer==0.15.2
@@ -161,6 +236,8 @@ typing-extensions==4.12.2
     #   typer
 ujson==5.10.0
     # via fastapi
+urllib3==2.5.0
+    # via requests
 uvicorn==0.34.0
     # via
     #   fastapi

docs/source/actions.rst

@@ -8,7 +8,7 @@ terms, any method of a `.Thing` that we want to be able to call over HTTP
 should be decorated as an Action, using :deco:`.thing_action`.
 
 This page gives an overview of how actions are implemented in LabThings-FastAPI.
-wot_cc_ includes a section on wot_actions_ that introduces the general concept.
+:ref:`wot_cc` includes a section on wot_:ref:`actions` that introduces the general concept.
 
 Running actions via HTTP
 ------------------------
@@ -54,6 +54,6 @@ the Thing Description, so it is important to use them consistently.
 There are some function arguments that are not considered input parameters.
 The first is ``self`` (the first positional argument), which is always the
 `.Thing` on which the argument is defined. The other special arguments are
-dependencies_, which use annotated type hints to tell LabThings to
+:ref:`dependencies`, which use annotated type hints to tell LabThings to
 supply resources needed by the action. Most often, this is a way of accessing
 other `.Things` on the same server.

docs/source/lt_core_concepts.rst

@@ -15,7 +15,7 @@ The server API is accessed over an HTTP requests, allowing client code (see belo
 Everything is a Thing
 ---------------------
 
-As described in wot_cc_, a Thing represents a piece of hardware or software. LabThings-FastAPI automatically generates a wot_td_ to describe each Thing. Each function offered by the Thing is either a Property or Action (LabThings-FastAPI does not yet support Events). These are termed "interaction affordances" in WoT_ terminology.
+As described in :ref:`wot_cc`, a Thing represents a piece of hardware or software. LabThings-FastAPI automatically generates a :ref:`wot_td` to describe each Thing. Each function offered by the Thing is either a Property or Action (LabThings-FastAPI does not yet support Events). These are termed "interaction affordances" in WoT_ terminology.
 
 Code on the LabThings FastAPI Server is composed of Things, however these can call generic Python functions/classes. The entire HTTP API served by the server is defined by `.Thing` objects. As such the full API is composed of the actions and properties (and perhaps eventually events) defined in each Thing.
 

docs/source/using_things.rst

@@ -28,9 +28,9 @@ One goal of LabThings-FastAPI is to make code portable between a client (e.g. a
 
 A `.DirectThingClient` class will call actions and properties of other `.Thing` subclasses using the same interface that would be used by a remote client, which means code for an action may be developed as an HTTP client, for example in a Jupyter notebook, and then moved to the server with minimal changes. Currently, there are a few differences in behaviour between working locally or remotely, most notably the return types (which are usually Pydantic models on the server, and currently dictionaries on the client). This should be improved in the future.
 
-It is also possible for a `.Thing` to access other `.Thing` instances directly. This gives access to functionality that is only available in Python, i.e. not available through a `.ThingClient` over HTTP. However, the `.Thing` must then be supplied manually with any dependencies_ required by its actions, and the public API as defined by the wot_td_ is no longer enforced.
+It is also possible for a `.Thing` to access other `.Thing` instances directly. This gives access to functionality that is only available in Python, i.e. not available through a `.ThingClient` over HTTP. However, the `.Thing` must then be supplied manually with any :ref:`dependencies` required by its actions, and the public API as defined by the :ref:`wot_td` is no longer enforced.
 
-Actions that make use of other `.Thing` objects on the same server should access them using dependencies_.
+Actions that make use of other `.Thing` objects on the same server should access them using :ref:`dependencies`.
 
 Planned future development: static code generation
 --------------------------------------------------

pyproject.toml

@@ -31,7 +31,14 @@ dev = [
   "ruff>=0.1.3",
   "types-jsonschema",
   "Pillow",
+  "flake8",
+  "flake8-pyproject",
+  "flake8-docstrings",
+  "flake8-rst",
+  "flake8-rst-docstrings",
   "pydoclint",
+  "sphinx-rtd-theme",
+  "sphinx>=7.2",
 ]
 
 [project.urls]
@@ -92,5 +99,19 @@ check-yield-types = false  # use type annotations instead
 [tool.mypy]
 plugins = ["pydantic.mypy", "numpy.typing.mypy_plugin"]
 
+[tool.flake8]
+extend-ignore = ["DOC301"]
+max-line-length = 88
+rst-roles = [
+    "class",
+    "func",
+    "ref",
+    "deco",
+    "doc",
+]
+rst-directives = [
+    "todo",
+]
+
 [project.scripts]
 labthings-server = "labthings_fastapi.server.cli:serve_from_cli"

src/labthings_fastapi/__init__.py

@@ -1,9 +1,11 @@
 r"""LabThings-FastAPI.
 
 This is the top level module for LabThings-FastAPI, a library for building
-wot_cc_ devices using Python. There is documentation on readthedocs_,
+:ref:`wot_cc` devices using Python. There is documentation on readthedocs_,
 and the recommended place to start is :doc:`index`\ .
 
+.. _readthedocs: https://labthings-fastapi.readthedocs.io/
+
 This module contains a number of convenience
 imports and is intended to be imported using:
 

src/labthings_fastapi/actions/__init__.py

@@ -3,7 +3,8 @@
 :ref:`wot_actions` are represented by methods, decorated with the `.thing_action`
 decorator.
 
-See the actions_ documentation for a top-level overview of actions in LabThings-FastAPI.
+See the :ref:`actions` documentation for a top-level overview of actions in
+LabThings-FastAPI.
 
 Developer notes
 ---------------

src/labthings_fastapi/client/__init__.py

@@ -33,7 +33,7 @@ class ObjectHasNoLinksError(KeyError):
 def _get_link(obj: dict, rel: str) -> Mapping:
     """Retrieve a link from an object's ``links`` list, by its ``rel`` attribute.
 
-    Various places in the wot_td_ feature a list of links. This is represented
+    Various places in the :ref:`wot_td` feature a list of links. This is represented
     in JSON as a property called ``links`` which is a list of objects that have
     ``href`` and ``rel`` properties.
 
@@ -160,7 +160,7 @@ def set_property(self, path: str, value: Any):
         r.raise_for_status()
 
     def invoke_action(self, path: str, **kwargs):
-        """Invoke an action on the Thing.
+        r"""Invoke an action on the Thing.
 
         This method will make the initial POST request to invoke an action,
         then poll the resulting invocation until it completes. If successful,
@@ -171,7 +171,7 @@ def invoke_action(self, path: str, **kwargs):
 
         :param path: the URI of the ``invokeaction`` endpoint, relative to the
             ``base_url``
-        :param **kwargs: Additional arguments will be combined into the JSON
+        :param \**kwargs: Additional arguments will be combined into the JSON
             body of the ``POST`` request and sent as input to the action.
             These will be validated on the server.
 
@@ -244,7 +244,7 @@ def subclass_from_td(cls, thing_description: dict) -> type[Self]:
         Dynamically subclass `.ThingClient` to add properties and
         methods for each property and action in the Thing Description.
 
-        :param thing_description: A wot_td_ as a dictionary, which will
+        :param thing_description: A :ref:`wot_td` as a dictionary, which will
             be used to construct the class.
 
         :return: a `.ThingClient` subclass with the right properties and
@@ -345,7 +345,7 @@ def add_action(cls: type[ThingClient], action_name: str, action: dict) -> None:
         action.
     :param action_name: is both the name we assign the method to, and
         the name of the action in the Thing Description.
-    :param action: a dictionary representing the action, in wot_td_
+    :param action: a dictionary representing the action, in :ref:`wot_td`
         format.
     """
 
@@ -371,7 +371,7 @@ def add_property(cls: type[ThingClient], property_name: str, property: dict):
         property.
     :param property_name: is both the name we assign the descriptor to, and
         the name of the property in the Thing Description.
-    :param property: a dictionary representing the property, in wot_td_
+    :param property: a dictionary representing the property, in :ref:`wot_td`
         format.
     """
     setattr(

src/labthings_fastapi/client/in_server.py

@@ -4,7 +4,7 @@
 use an interface that is identical to the `.ThingClient` used to access
 the same `.Thing` remotely. This means that code can run either on the
 server or on a client, e.g. in a Jupyter notebook where it is much
-easier to debug. See things_from_things_ for more detail.
+easier to debug. See :ref:`things_from_things` for more detail.
 
 Currently `.DirectThingClient` is not a subclass of `.ThingClient`,
 that may need to change. It's a good idea to create a
@@ -55,15 +55,15 @@ class DirectThingClient:
     """The path to the Thing on the server. Relative to the server's base URL."""
 
     def __init__(self, request: Request, **dependencies: Mapping[str, Any]):
-        """Wrap a `.Thing` so it works like a `.ThingClient`.
+        r"""Wrap a `.Thing` so it works like a `.ThingClient`.
 
         This class is designed to be used as a FastAPI dependency, and will
         retrieve a `.Thing` based on its ``thing_path`` attribute.
         Finding the Thing by class may also be an option in the future.
 
         :param request: This is a FastAPI dependency to access the
             `fastapi.Request` object, allowing access to various resources.
-        :param **dependencies: Further arguments will be added
+        :param \**dependencies: Further arguments will be added
             dynamically by subclasses, by duplicating this method and
             manipulating its signature. Adding arguments with annotated
             type hints instructs FastAPI to inject dependency arguments,
@@ -139,7 +139,7 @@ class DependencyNameClashError(KeyError):
     """A dependency argument name is used inconsistently.
 
     A current limitation of `.DirectThingClient` is that the dependency
-    arguments (see dependencies_) are collected together in a single
+    arguments (see :ref:`dependencies`) are collected together in a single
     dictionary. This makes the assumption that, if a name is reused, it is
     reused for the same dependency.
 
@@ -247,7 +247,7 @@ def direct_thing_client_class(
     thing_path: str,
     actions: Optional[list[str]] = None,
 ) -> type[DirectThingClient]:
-    """Create a DirectThingClient from a Thing class and a path.
+    r"""Create a DirectThingClient from a Thing class and a path.
 
     This is a class, not an instance: it's designed to be a FastAPI dependency.
 
@@ -258,11 +258,11 @@ def direct_thing_client_class(
         dependencies we need.
 
     :return: a subclass of `DirectThingClient` with attributes that match the
-        properties and actions of ``thing_class``. The ``__init__` method
+        properties and actions of ``thing_class``. The ``__init__`` method
         will have annotations that instruct FastAPI to supply all the
         dependencies needed by its actions.
 
-        This class may be used as a FastAPI dependency: see things_from_things_.
+        This class may be used as a FastAPI dependency: see :ref:`things_from_things`.
     """
 
     def init_proxy(self, request: Request, **dependencies: Mapping[str, Any]):