docs: fix minor mistakes and links for 'typing.Self'.

Signed-off-by: Romain Bezut <[email protected]>

aio_ld2410/ld2410.py

@@ -341,10 +341,13 @@ async def configure(self) -> AsyncIterator[ConfigModeStatus]:
         Yields:
             Device's protocol information.
 
-            This is the standard reply for command :attr:`.CommandCode.CONFIG_ENABLE`.
+            This is the standard reply for command :attr:`~.CommandCode.CONFIG_ENABLE`.
 
             You most likely don't need this returned value.
 
+        Returns:
+            An asynchronous iterator (seel YIELDS).
+
         """
         async with self._config_lock:
             resp = await self._request(CommandCode.CONFIG_ENABLE)
@@ -513,6 +516,9 @@ async def get_reports(self) -> AsyncIterator[ReportStatus]:
         Yields:
             An asynchronous iterator for :class:`.ReportStatus`.
 
+        Returns:
+            An asynchronous iterator (seel YIELDS).
+
         """
         while True:
             yield await self.get_next_report()

aio_ld2410/protocol/frame.py

@@ -13,7 +13,9 @@
 class FrameType(IntEnum):
     """All known frame types handled by the device."""
 
+    #: This frame is a command or reply frame.
     COMMAND = 1
+    #: This frame is a report frame.
     REPORT = 2
 
 

aio_ld2410/protocol/report.py

@@ -10,8 +10,11 @@
 class ReportType(IntEnum):
     """Type of report we received."""
 
-    ENGINEERING = 1  #: Advanced report with per-gate values.
-    BASIC = 2  #: Basic report for an easy use.
+    #: Advanced report with per-gate values.
+    ENGINEERING = 1
+
+    #: Basic report for an easy use.
+    BASIC = 2
 
 
 class TargetStatus(IntFlag):
@@ -21,8 +24,6 @@ class TargetStatus(IntFlag):
     This field is present in reports and tells whether the target (if any)
     is static, moving or both.
 
-    Note that this class derives from :class:`enum.IntFlag`.
-
     """
 
     MOVING = 1  #: There is a moving target

docs/conf.py

@@ -11,6 +11,18 @@
 import inspect
 import os
 import sys
+from typing import TYPE_CHECKING
+
+from sphinx.ext.intersphinx import missing_reference
+from sphinx.util.inspect import TypeAliasForwardRef
+
+if TYPE_CHECKING:
+    from docutils import nodes
+    from docutils.nodes import TextElement
+    from sphinx.addnodes import pending_xref
+    from sphinx.application import Sphinx
+    from sphinx.config import Config
+    from sphinx.environment import BuildEnvironment
 
 # -- Path setup --------------------------------------------------------------
 
@@ -23,6 +35,7 @@
 # https://www.sphinx-doc.org/en/master/usage/configuration.html#general-configuration
 author = 'Romain Bezut'
 project = 'aio-ld2410'
+package = project.replace('-', '_')
 copyright = f'2024, {author}'
 
 extensions = [
@@ -49,6 +62,7 @@
 ]
 
 # Napoleon settings
+napoleon_preprocess_types = True
 napoleon_use_admonition_for_notes = True
 
 # Autodoc
@@ -69,10 +83,23 @@
 
 # InterSphinx
 intersphinx_mapping = {
-    'python': ('https://docs.python.org/3', None),
     'construct': ('https://construct.readthedocs.io/en/latest', None),
+    'python': ('https://docs.python.org/3', None),
+}
+# Map of references known to be broken by default.
+# We register a custom mapper linked to intersphinx.
+_reftarget_fixmap = {
+    'asyncio.locks.Condition': 'asyncio.Condition',
+    'asyncio.streams.StreamReader': 'asyncio.StreamReader',
+    'asyncio.streams.StreamWriter': 'asyncio.StreamWriter',
+}
+# Map of known types that get badly requested to be a class.
+_reftype_fixmap = {
+    'typing.Annotated': 'obj',
+    'typing.Self': 'obj',
 }
 
+
 # OpenGraph
 ogp_site_url = os.environ.get(
     'READTHEDOCS_CANONICAL_URL',
@@ -160,7 +187,6 @@ def linkcode_resolve(domain, info):
 # https://www.sphinx-doc.org/en/master/usage/configuration.html#options-for-html-output
 
 html_theme = 'furo'
-
 html_theme_options = {
     'source_repository': repo_url,
     'source_branch': commit,
@@ -181,12 +207,50 @@ def linkcode_resolve(domain, info):
 # relative to this directory. They are copied after the builtin static files,
 # so a file named "default.css" will overwrite the builtin "default.css".
 html_static_path = ['_static']
-html_css_files = [
-    'css/custom.css',
-]
-
+html_css_files = ['css/custom.css']
 html_copy_source = False
 html_show_sourcelink = True
 html_show_sphinx = False
 html_logo = '_static/aio-ld2410.png'
 html_favicon = '_static/favicon.png'
+
+
+def custom_missing_reference(
+    app: Sphinx,
+    env: BuildEnvironment,
+    node: pending_xref,
+    contnode: TextElement,
+) -> nodes.reference | None:
+    """Fix references that are known not to exist."""
+    reftarget = node['reftarget']
+
+    newtarget = _reftarget_fixmap.get(reftarget)
+    if newtarget is not None:
+        node['reftarget'] = reftarget = newtarget
+
+    newtype = _reftype_fixmap.get(reftarget)
+    if newtype is not None:
+        node['reftype'] = newtype
+
+    if isinstance(reftarget, str) and reftarget.startswith(f'{package}.'):
+        domain = env.domains[node['refdomain']]
+        refdoc = node.setdefault('refdoc', env.docname)
+        result = domain.resolve_xref(
+            env,
+            refdoc,
+            app.builder,
+            node['reftype'],
+            reftarget,
+            node,
+            contnode,
+        )
+    else:
+        result = missing_reference(app, env, node, contnode)
+
+    # Look for an external reference now that we fixed the target or target type.
+    return result
+
+
+def setup(app: Sphinx) -> None:
+    """Add a custom methid for missing references."""
+    app.connect('missing-reference', custom_missing_reference)

tests/requirements-linting.txt

@@ -1,4 +1,4 @@
 mypy==1.13.0
-ruff==0.7.3
+ruff==0.8.1
 construct-typing==0.6.2
 typing_extensions==4.12.2

tests/requirements-testing.txt

@@ -1,5 +1,5 @@
 anyio==4.6.2.post1
-coverage==7.6.4
+coverage==7.6.8
 pytest-cov==6.0.0
 pytest-timeout==2.3.1
-pytest==8.3.3
+pytest==8.3.4