docs(conf): fix class signatures, defaults, aenum names, table ids and viewcode's index (#1858, #1859, #1860, #1861, #1862, #1863)

[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

---

Stacked on #1877. It contains #1877's commit until that merges, so merge #1877 first. This PR's own commit is 0f93ff5cf.

All six fixes are in docs/source/conf.py. The figures below are from builds under the pinned sphinx-autodoc-typehints 3.15.0, comparing #1877's head with this commit.

• docs: aenum and stdlib enum unions render as IntEnum | IntEnum and Enum | Enum #1858: aenum classes render as aenum.IntEnum, so IntEnum | IntEnum is gone from every page.
• docs: signature defaults render by value, so sys.byteorder shows the build host's 'little' #1859: autodoc_preserve_defaults is on, so byteorder=sys.byteorder replaces the build host's value. A default reached through a private import alias is named by its own class.
• docs: Info and Schema subclasses render the base __new__'s (*args, **kwargs) signature, not their fields #1860: a class whose __init__ is hidden by __new__ gets that __init__'s parameters. Class catch-all signatures went from 991 to 71. The 71 left are unfinalised Info/Schema bases, whose real __init__ is generated on first use.
• docs: furo copies a titled table's id onto its wrapper, so const/reg.html carries duplicate ids #1861: a post-transform moves wrapped tables' ids off furo's table-wrapper, so const/reg.html has no duplicate ids.
• docs: memberless enums render the functional-API call signature #1862: every enumeration shows (*values).
• docs: the viewcode module index links a builtins page that is never generated #1863: _modules/index.html no longer links a missing builtins.html.

Worth a look. To restore class parameter types in docstrings under 3.15.0, read_constructor_types_from_init repoints the library's private constructor_name. It is a separable hunk if patching the library is unwanted.

Both builds finish with 0 warnings. Each new tests/project module fails with its fix reverted. Full tests/project: 1016 passed, 7 skipped.

Closes #1858
Closes #1859
Closes #1860
Closes #1861
Closes #1862
Closes #1863

[JarryShaw]

Verdict: NEEDS CHANGES at 0f93ff5cf. A Sonnet cross-review confirmed every load-bearing claim. The only required changes are three counts this PR adds to prose:

1. docs/source/conf.py:960: "its two modules that read it". Drop the number.
2. docs/source/conf.py:981: "id9 to id13 on const/reg.html". That id range is generated by the build and goes stale when the page changes. Describe the titled tables instead.
3. tests/project/test_docs_class_signature_1860_unit.py:216: "Both modules…". Rephrase without a count.

What the review confirmed:

• Restored signatures are correct. Every restored signature uses the function cls.__init__ actually resolves to, and real constructions accept or reject arguments as the signatures say. Classes without a Python __new__ are untouched.
• The private patch is safe. read_constructor_types_from_init is gated on the typehints release. If a release renames the private attribute, it raises at builder-inited rather than patching nothing. typehints 3.16.0 changes nothing relevant.
• The tests are real. Each of the six fixes, reverted on its own, fails its test on a real assertion.
• The rendering fixes reproduce. In an independent 3.15.0 build (Python 3.14 and 3.15, also with typehints 3.16.0) there are 0 warnings, catch-alls fall from 991 to 71, and the duplicate ids, IntEnum | IntEnum and the builtins.html link are all gone. tests/project: 1018 passed, 5 skipped.

Optional: hidden_init's non-pass-through __new__ branch is not pinned by any test, and the pre-3.14 typehints_constructor_name fallback is never used. My description was also loose: the 71 remaining catch-alls include FieldBase/NoValueField, whose own __init__ takes *args, **kwargs.

[JarryShaw]

Verdict: GOOD TO GO at 3cabc1465. The Sonnet reviewer re-checked the changes since 0f93ff5cf.

• The three counts are gone, and a scan of the whole PR finds no other counted number in its prose.
• test_new_with_parameters_is_left_to_autodoc fails when hidden_init's non-pass-through __new__ branch is removed, so that branch is now covered.
• Removing the pre-3.14 fallback is safe. The names it defined are reached only through setup's 3.14-and-later branch. Under typehints 3.13.6, conf.py loads, setup() runs and a full docs build succeeds, with no NameError.
• Each test_docs_*_18xx_unit file passes on its own, under typehints 3.15.0 and under 3.13.6.

Merge #1877 first: this PR is stacked on it.

[JarryShaw]

what about we pin the typehints version so we dont need the branching?

[JarryShaw]

Agreed. docs/requirements.txt already pins 3.15.0 exactly (#1877). The branching only exists for environments that install the unpinned sphinx-autodoc-typehints from the docs extra in pyproject.toml, such as an older local venv in which tests/project loads conf.py.

The plan:

• Pin the docs extra to the same release, with a test that the two pins agree.
• Drop every release branch from conf.py: docs(conf): build with sphinx-autodoc-typehints 3.15.0 (#1856) #1877's _resolver fallback, and this PR's pre-3.14 paths.
• Make the conf.py tests skip, with a clear reason, when the installed release isn't the pinned one, instead of carrying a code path for it.

A worker will add this to #1877 and rebase this PR onto it. Both review labels reset when the new heads land.

[JarryShaw]

Verdict: NEEDS CHANGES at 8c796f6c2. The rebase removes every release branch. The new furo provider and HAS_FURO exclusion fix the tier-guard failure that the earlier head 3cabc1465 would have hit (18 failed there, 111 passed now). Every test_docs_* file passes under 3.15.0 and skips cleanly under 3.13.6. A 3.15.0 docs build gives 0 warnings, and the #1858, #1860, #1861, #1862 and #1863 fixes show in the HTML.

One required change, the same as on #1877. The HAS_FURO reason (tests/_dependency_gates.py:~652) repeats that the docs extra is one "which only deploy-pages.yml installs". No workflow installs the docs extra: deploy-pages installs furo through docs/requirements.txt.

[JarryShaw]

Verdict: GOOD TO GO at ec97be1e0. This is the rebase onto #1877's 57922c032. The only change is in tests/_dependency_gates.py: the HAS_SPHINX issue list now names #1858–#1863 and the enum-value hook, which the reviewer checked against the gated modules, and the HAS_FURO reason is corrected the same way as #1877's. test_tier_guard.py gives 111 passed.

Merge #1877 first.

[github-actions]

Coverage: 90.05% (unit tier, Python 3.15, ec97be1e0, 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.

[JarryShaw]

Resolve conflicts

[JarryShaw]

Verdict: GOOD TO GO at 3cdb89c7f. Conflicts resolved: rebased onto main as one commit. #1877's two commits dropped out because they are already on main. In tests/_dependency_gates.py, #1871's docutils entries stay byte-identical, with this PR's furo entries after them.

A Sonnet re-review confirmed four things:

• The commit's changed lines match the previous head's exactly.
• docs(conf): build with sphinx-autodoc-typehints 3.15.0 (#1856) #1877's pin handling is neither reverted nor duplicated.
• The tier guard and tests/project pass.
• The new docs tests pass under the pinned sphinx-autodoc-typehints.