docs(conf): build with sphinx-autodoc-typehints 3.15.0 (#1856)

[JarryShaw]

Please follow the guide below

• You will be asked some questions, please read them carefully and answer honestly

• Put an x into all the boxes [ ] relevant to your pull request (like that [x])

• Use Preview tab to see how your pull request will actually look like

• Searched for similar pull requests

• Followed the coding style (make pylint, make mypy, make isort)

• make test passes, and a test case covers the change. Narrow runs only, listed below.

• Added a changelog entry under docs/source/changelog/ and regenerated CHANGELOG.md, if the change is user-visible: N/A — centralised in docs(changelog): shared 1.5.0 changelog — long-lived, merges last (#610, #616, #617, #618, #620) #657

What is the purpose of your pull request?

Tick the commit type your subject line carries.

• fix — corrects a defect
• feat — adds a feature
• perf — changes performance, not behaviour
• refactor — changes neither behaviour nor performance
• test — tests only
• docs — documentation only
• ci — workflows or build tooling
• release — bumps the version or rolls up a distribution
• chore — anything else

---

• Pin sphinx-autodoc-typehints to 3.15.0 in docs/requirements.txt.
• Import resolve_type_guarded_imports from _resolve from 3.14 on and from
  _resolver before it, chosen by the installed release, so each branch is a
  plain import that still fails loudly if the private API moves again.
• From 3.14 the library records a module's TYPE_CHECKING names instead of
  binding them, so Sphinx's own signature introspection lost them and schema
  signatures linked the wrong _VT; bind_guarded_names binds them again.
• Run bind_type_checking_names on env-before-read-docs, after the library
  clears its guard record there.
• Connect claim_attribute_signature only before 3.14, whose handler no longer
  returns a signature for an attribute.
• Add tests/project/test_docs_typehints_pin_1856_unit.py.

Closes #1856

Heads-up: rendering regression. 3.15.0 itself changes 273 signatures in the build, and 129 classes now render as (*args, **kwargs). That includes protocol classes such as FTP(file=None, length=None, **kwargs), plus reassembly, traceflow and Info classes that rendered correctly before. Version 3.15.0 takes the class signature from __new__ when a class defines both __new__ and __init__, and ProtocolBase, Reassembly, TraceFlow and Info each define a pass-through __new__. The fix is an autodoc-process-signature hook in conf.py, which belongs with #1860. #1860's scope is widened to cover these classes, and the conf.py batch (#1858–#1863) builds on this branch.

[JarryShaw]

Verdict: GOOD TO GO at 2fef298da. A Sonnet cross-review (author: Opus) confirmed:

• The move. resolve_type_guarded_imports moved in 3.14.0 (_resolver → _resolve/guards/run.py, re-exported from _resolve). It is unchanged in 3.15.0 and in 3.16.0, which was released today.
• The import. The version-selected import loads with the real 3.13.6 and 3.15.0, and raises ModuleNotFoundError in both directions when the reported version is patched wrong.
• bind_guarded_names. It only fills names a module lacks (setdefault). A walk over every pcapkit module bound only real objects, with no placeholders and no builtin shadows. It runs only inside a Sphinx event, so importing conf.py binds nothing.
• Event priority. The library clears its record on env-before-read-docs at 500, so 600 runs after it.
• Builds. A clean build with 3.15.0 reports 0 warnings, and removing the binding loop reproduces exactly 815. Overload blocks now link. 273 signature texts changed, as stated.

Correction to the PR body: the "18 in the baseline" came from a local venv with 3.13.6. Under the pinned 3.13.9 the baseline is also 0 warnings, so the gain is the linking, not a warning count.

Merge note: on its own, this publishes (*args, **kwargs) for the collapsed classes (about 130, including FTP, IP and Info) until the conf.py batch for #1858–#1863 lands. That batch is stacked on this branch and in progress, so merging the two together keeps the live docs clean.

[JarryShaw]

Verdict: NEEDS CHANGES at 9b59d108d. The pin works:

• The docs extra and docs/requirements.txt both pin sphinx-autodoc-typehints==3.15.0, and the agreement test fails if either changes.
• conf.py has no release branching left.
• The docs tests skip with the pin reason under 3.13.6 and 3.16.0.
• A 3.15.0 docs build gives 0 warnings.

One required change. The rewritten HAS_SPHINX reason in tests/_dependency_gates.py:~630 says the docs extra is one "which only deploy-pages.yml installs". No workflow installs the docs extra. deploy-pages.yml:167-168 installs docs/requirements.txt and .[all,dev], which I checked. Say that deploy-pages installs Sphinx from docs/requirements.txt and no workflow installs the docs extra itself.

[JarryShaw]

Verdict: GOOD TO GO at 57922c032. The Sonnet reviewer checked the last change, which touches only the HAS_SPHINX reason. It now says, correctly, that only deploy-pages installs Sphinx and the pinned sphinx-autodoc-typehints, from docs/requirements.txt, and that no workflow installs the docs extra. test_tier_guard.py gives 111 passed.

The earlier rounds' results stand:

• the pin-agreement test fails under every pin mutation;
• conf.py has no release branching;
• the docs tests skip with the pin reason under other releases;
• the 3.15.0 build gives 0 warnings.

[github-actions]

Coverage: 90.05% (unit tier, Python 3.15, 57922c032, Unit Tests run success)

Package	Statements	Missed	Branches	Partial	Cover
pcapkit (top level)	104	2	20	2	96.77%
pcapkit/const	19595	881	2618	867	92.11%
pcapkit/corekit	2462	69	780	35	96.55%
pcapkit/dumpkit	276	3	100	3	98.40%
pcapkit/foundation	2914	164	1016	34	93.59%
pcapkit/interface	138	7	52	5	93.68%
pcapkit/protocols	17406	224	4580	189	98.10%
pcapkit/toolkit	872	177	298	8	77.18%
pcapkit/utilities	512	2	158	4	99.10%
pcapkit/vendor	4407	2342	1010	157	43.27%

Per-file detail: the coverage-html artifact of this run.