From 7c256eb31ed2ba06336b8ab590e11af14f209d74 Mon Sep 17 00:00:00 2001 From: Tony Narlock Date: Sat, 25 Jul 2026 12:22:57 -0500 Subject: [PATCH 1/2] linkify_issues(docs[SetupDict]): Document fields why: Sphinx autodoc renders TypedDict fields whether or not they are described, so the extension metadata keys ship to the API reference bare, leaving readers to guess what the setup mapping promises Sphinx. what: - Add an Attributes section to SetupDict covering the extension version and the parallel read/write safety flags --- src/linkify_issues.py | 15 ++++++++++++++- 1 file changed, 14 insertions(+), 1 deletion(-) diff --git a/src/linkify_issues.py b/src/linkify_issues.py index 0d0c0db..ee935d7 100644 --- a/src/linkify_issues.py +++ b/src/linkify_issues.py @@ -68,7 +68,20 @@ def condition(node: nodes.Node) -> bool: class SetupDict(t.TypedDict): - """Setup mapping for Sphinx app.""" + """Setup mapping for Sphinx app. + + Attributes + ---------- + version : str + Version of this extension, returned to Sphinx so it can invalidate + its build environment when the extension changes. + parallel_read_safe : bool + Whether Sphinx may read source files in parallel while this + extension is loaded. + parallel_write_safe : bool + Whether Sphinx may write output in parallel while this extension is + loaded. + """ version: str parallel_read_safe: bool From d042bae1272ccedeedebd69ea49cf59ba0b96501 Mon Sep 17 00:00:00 2001 From: Tony Narlock Date: Sat, 25 Jul 2026 20:13:10 -0500 Subject: [PATCH 2/2] docs(CHANGES) Documented class fields why: The unreleased entry did not record that class fields now carry descriptions where the API reference renders them. what: - Note the described fields under Documentation --- CHANGES | 8 ++++++++ 1 file changed, 8 insertions(+) diff --git a/CHANGES b/CHANGES index 1c53c1b..b2e944a 100644 --- a/CHANGES +++ b/CHANGES @@ -32,6 +32,14 @@ $ uvx --from 'gp-libs' --prerelease allow gp-libs _Notes on upcoming releases will be added here_ +### Documentation + +#### Extension metadata fields are described (#81) + +The `TypedDict` returned from `linkify_issues`'s Sphinx `setup()` now says +what each key holds. They previously reached the rendered API reference as +"Alias for field number 0" or as a bare name carrying only its type. + ### Development #### CI actions updated to current majors