From 1662bd53f509be3a551a0c47e5a868a095ebe8db Mon Sep 17 00:00:00 2001 From: Stefan VanBuren Date: Wed, 30 Sep 2026 08:56:15 -0400 Subject: [PATCH] Fix docs cross-refs and fail the docs build on warnings The `connectrpc_grpcreflect` docstrings linked to `connectrpc.grpcreflect.*`, and `ErrorDetail.__init__` linked to a bare `[value()][]`; neither resolved, so `zensical` emitted nine warnings. CI missed them for two reasons: 1. `zensical build` exits 0 on warnings. `docs-build` now passes `--strict`; `docs-serve` stays lenient. 2. The docs workflow only ran on changes under `docs/` and `src/`, so edits to `connectrpc-grpcreflect` and `connectrpc-otel` never triggered it, even though `api.md` renders both. Signed-off-by: Stefan VanBuren --- .github/workflows/docs.yaml | 4 ++++ .../connectrpc_grpcreflect/_service.py | 16 ++++++++-------- poe_tasks.toml | 2 +- src/connectrpc/errors.py | 2 +- 4 files changed, 14 insertions(+), 10 deletions(-) diff --git a/.github/workflows/docs.yaml b/.github/workflows/docs.yaml index cdf5c9e..c65e78f 100644 --- a/.github/workflows/docs.yaml +++ b/.github/workflows/docs.yaml @@ -6,12 +6,16 @@ on: paths: - "docs/**" - "src/**" + - "connectrpc-grpcreflect/**" + - "connectrpc-otel/**" - zensical.toml - ".github/workflows/docs.yaml" pull_request: paths: - "docs/**" - "src/**" + - "connectrpc-grpcreflect/**" + - "connectrpc-otel/**" - zensical.toml - ".github/workflows/docs.yaml" diff --git a/connectrpc-grpcreflect/connectrpc_grpcreflect/_service.py b/connectrpc-grpcreflect/connectrpc_grpcreflect/_service.py index 0c680ad..294506f 100644 --- a/connectrpc-grpcreflect/connectrpc_grpcreflect/_service.py +++ b/connectrpc-grpcreflect/connectrpc_grpcreflect/_service.py @@ -53,8 +53,8 @@ def __init__(self, *descs: DescFile | DescService) -> None: *descs: The descriptors to make available for reflection. Returns: - A new instance of [ServerReflectionService][connectrpc.grpcreflect.ServerReflectionService], - for use with [ServerReflectionASGIApplication][connectrpc.grpcreflect.ServerReflectionASGIApplication]. + A new instance of [ServerReflectionService][connectrpc_grpcreflect.ServerReflectionService], + for use with [ServerReflectionASGIApplication][connectrpc_grpcreflect.ServerReflectionASGIApplication]. """ registry, service_names = _resolve_registry(descs) @@ -86,8 +86,8 @@ def __init__(self, *descs: DescFile | DescService) -> None: *descs: The descriptors to make available for reflection. Returns: - A new instance of [ServerReflectionServiceSync][connectrpc.grpcreflect.ServerReflectionServiceSync], - for use with [ServerReflectionWSGIApplication][connectrpc.grpcreflect.ServerReflectionWSGIApplication]. + A new instance of [ServerReflectionServiceSync][connectrpc_grpcreflect.ServerReflectionServiceSync], + for use with [ServerReflectionWSGIApplication][connectrpc_grpcreflect.ServerReflectionWSGIApplication]. """ registry, service_names = _resolve_registry(descs) @@ -123,8 +123,8 @@ def __init__(self, *descs: DescFile | DescService) -> None: *descs: The descriptors to make available for reflection. Returns: - A new instance of [ServerReflectionAlphaService][connectrpc.grpcreflect.ServerReflectionAlphaService], - for use with [ServerReflectionAlphaASGIApplication][connectrpc.grpcreflect.ServerReflectionAlphaASGIApplication]. + A new instance of [ServerReflectionAlphaService][connectrpc_grpcreflect.ServerReflectionAlphaService], + for use with [ServerReflectionAlphaASGIApplication][connectrpc_grpcreflect.ServerReflectionAlphaASGIApplication]. """ registry, service_names = _resolve_registry(descs) @@ -165,8 +165,8 @@ def __init__(self, *descs: DescFile | DescService) -> None: *descs: The descriptors to make available for reflection. Returns: - A new instance of [ServerReflectionAlphaServiceSync][connectrpc.grpcreflect.ServerReflectionAlphaServiceSync], - for use with [ServerReflectionAlphaWSGIApplication][connectrpc.grpcreflect.ServerReflectionAlphaWSGIApplication]. + A new instance of [ServerReflectionAlphaServiceSync][connectrpc_grpcreflect.ServerReflectionAlphaServiceSync], + for use with [ServerReflectionAlphaWSGIApplication][connectrpc_grpcreflect.ServerReflectionAlphaWSGIApplication]. """ registry, service_names = _resolve_registry(descs) diff --git a/poe_tasks.toml b/poe_tasks.toml index 24cac5f..38c14b4 100644 --- a/poe_tasks.toml +++ b/poe_tasks.toml @@ -25,7 +25,7 @@ sequence = [ [tasks.docs-build] help = "Build documentation" -cmd = "uv run --group docs zensical build" +cmd = "uv run --group docs zensical build --strict" [tasks.docs-serve] help = "Start documentation local server" diff --git a/src/connectrpc/errors.py b/src/connectrpc/errors.py index b4537a9..a34d3eb 100644 --- a/src/connectrpc/errors.py +++ b/src/connectrpc/errors.py @@ -33,7 +33,7 @@ def __init__(self, message: Message) -> None: """Create a new error detail from a Protobuf message. If the message is an Any, it is used directly. Otherwise, the message - is packed into an Any, with it also stored to be recoverable from [value()][]. + is packed into an Any, with it also stored to be recoverable from [value()][connectrpc.errors.ErrorDetail.value]. """ if isinstance(message, Any): self._message = None