From 4e63b07789f52645f4cb82da554dc98211c3b7fd Mon Sep 17 00:00:00 2001 From: Jarry Shaw Date: Sat, 19 Sep 2026 11:57:36 -0400 Subject: [PATCH] docs: set PCAPKIT_SPHINX before importing pcapkit, not after `pcapkit/utilities/logging.py:73` computes `SPHINX_TYPE_CHECKING` from `os.environ` at *import* time, and `conf.py` imported `pcapkit` six lines before setting the variable. Since importing `pcapkit` already pulls in the schema modules, every `if SPHINX_TYPE_CHECKING:` TypedDict was left undefined and autodoc could not document it. - move the assignment above `import pcapkit`, with a comment saying why the order is load-bearing Measured both orderings against `pcapkit.protocols.schema.application.httpv2`, whose `FrameFlags` sits under that guard at line 36: set after import -> SPHINX_TYPE_CHECKING = False, has FrameFlags = False set before import -> SPHINX_TYPE_CHECKING = True, has FrameFlags = True This clears 96 `autodoc: failed to import` warnings and restores 89 documented members to the built HTML. All 89 names exist; none were stale. --- docs/source/conf.py | 9 +++++++-- 1 file changed, 7 insertions(+), 2 deletions(-) diff --git a/docs/source/conf.py b/docs/source/conf.py index 5037c04b1..ac018b71c 100644 --- a/docs/source/conf.py +++ b/docs/source/conf.py @@ -20,14 +20,19 @@ # silently goes back to emitting unresolvable annotations. from sphinx_autodoc_typehints._resolver import resolve_type_guarded_imports +# NB: this must precede ``import pcapkit``. ``pcapkit.utilities.logging`` reads +# ``PCAPKIT_SPHINX`` at *import* time to compute ``SPHINX_TYPE_CHECKING``, and +# importing ``pcapkit`` already pulls in the schema modules -- so setting it any +# later leaves every ``if SPHINX_TYPE_CHECKING:`` TypedDict undefined and autodoc +# cannot document them. +os.environ['PCAPKIT_SPHINX'] = '1' + import pcapkit if TYPE_CHECKING: from typing import Any, Dict, List, Optional from sphinx.application import Sphinx -os.environ['PCAPKIT_SPHINX'] = '1' - logger = logging.getLogger('pcapkit-sphinx') logger.setLevel(logging.INFO)