From 1fc746e7c05ae9d89ee317db737d5d2647574699 Mon Sep 17 00:00:00 2001 From: Romain Bezut Date: Sun, 1 Dec 2024 16:58:39 +0100 Subject: [PATCH] docs: fix minor mistakes and links for 'typing.Self'. Signed-off-by: Romain Bezut --- aio_ld2410/ld2410.py | 8 +++- aio_ld2410/protocol/frame.py | 2 + aio_ld2410/protocol/report.py | 9 ++-- docs/conf.py | 76 +++++++++++++++++++++++++++++++--- tests/requirements-linting.txt | 2 +- tests/requirements-testing.txt | 4 +- 6 files changed, 87 insertions(+), 14 deletions(-) diff --git a/aio_ld2410/ld2410.py b/aio_ld2410/ld2410.py index 3f6a956..d9b15d4 100644 --- a/aio_ld2410/ld2410.py +++ b/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() diff --git a/aio_ld2410/protocol/frame.py b/aio_ld2410/protocol/frame.py index 5a6740e..8c0db63 100644 --- a/aio_ld2410/protocol/frame.py +++ b/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 diff --git a/aio_ld2410/protocol/report.py b/aio_ld2410/protocol/report.py index 23b9027..0eabcfb 100644 --- a/aio_ld2410/protocol/report.py +++ b/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 diff --git a/docs/conf.py b/docs/conf.py index dfd9a9a..ae59cf2 100644 --- a/docs/conf.py +++ b/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) diff --git a/tests/requirements-linting.txt b/tests/requirements-linting.txt index 8cb09ba..60f45de 100644 --- a/tests/requirements-linting.txt +++ b/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 diff --git a/tests/requirements-testing.txt b/tests/requirements-testing.txt index f0c3563..e1b28f9 100644 --- a/tests/requirements-testing.txt +++ b/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