[JarryShaw]

• 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
• Added a changelog entry — 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?

• fix — bug fixes

---

Description of your pull request and other information

Closes #2094. In napoleon (Sphinx 9.1.0), Warns: went through _format_fields and came out as :Warns: **Name** -- desc: bold, with no role, and with a ~ printed literally. Raises: instead becomes :raises Name:, which the Python domain links.

• Fix: docs/source/conf.py's setup replaces GoogleDocstring._parse_warns_section, which the NumPy style inherits. Each name becomes :exc:`.Name`, which gets the same suffix search as Raises. A ~ prefix still shortens the title, and builtins resolve exactly through intersphinx. Comma lists are split; roles, literals and name (type) are left alone. No docstring changes.
• Build: under the pinned docs env (from docs/requirements.txt, as in deploy-pages.yml), there are 0 warnings before and after. Of the 62 warning names in Warns sections, all are now links where all were plain text before.
• Test: test_docs_warns_xrefs_2094_unit runs napoleon in both styles with the build's settings. It resolves each Warns name and its :raises: counterpart through the Python domain and checks they land on the same target. With conf.py reverted to main, 12 of its 15 tests fail. It needs Sphinx and the pinned sphinx-autodoc-typehints, and skips without them, like the other docs tests.

[JarryShaw]

GOOD TO GO at 786712130 (Sonnet review).

• Hook: the override keeps napoleon's own _consume_fields() and _format_fields(translate('Warns'), …), so labels, bullets and descriptions are unchanged. It rewrites only entries that have a name and no type. It is a plain class-attribute assignment, so running setup twice changes nothing, and it takes effect before any docstring is parsed.
• Corpus: every Warns: name is bare or dotted, and each is defined only in pcapkit/utilities/warnings.py, so no suffix match is ambiguous. The leading dot sets the same refspecific that :raises: does.
• Test: under a throwaway venv built from docs/requirements.txt it gives 9 passed with 6 subtests. With main's conf.py swapped in, 12 of 15 checks fail.
• Correction to the review: it found no CI job that runs this test unskipped. That was wrong. Unit Tests' Project tests job installs .[…,docs,…] (Sphinx plus sphinx-autodoc-typehints==3.17.2) and runs the tests/project pins. On main that job reports only 5 skips, so the docs tests run there. That job installs Sphinx 9.2.0 rather than docs/requirements.txt's 9.1.0, and this PR's Project tests result will show whether the hook holds on 9.2.0.

[github-actions]

Coverage: 91.54% (unit tier, Python 3.15, 786712130, Unit Tests run success)

Package	Statements	Missed	Branches	Partial	Cover
pcapkit (top level)	104	4	20	2	95.16%
pcapkit/const	19599	880	2618	866	92.12%
pcapkit/corekit	2565	71	812	37	96.56%
pcapkit/dumpkit	282	3	102	3	98.44%
pcapkit/foundation	2930	23	1022	25	98.79%
pcapkit/interface	138	4	52	3	96.32%
pcapkit/protocols	17414	219	4574	185	98.14%
pcapkit/toolkit	869	36	298	10	95.20%
pcapkit/utilities	473	7	136	5	98.03%
pcapkit/vendor	4432	1988	1018	167	51.87%

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