From 4ea6027a672e9212f61fa6f49c20989a7adda5c3 Mon Sep 17 00:00:00 2001 From: Jarry Shaw Date: Sun, 1 Nov 2026 11:16:59 -0500 Subject: [PATCH 1/2] docs(pcapkit): give every undocumented shipped module a page (#2559) - Add const/linux.rst, vendor/tls.rst and vendor/sslv2.rst, mirroring vendor/linux.rst, const/tls.rst and const/sslv2.rst, and list them in the const and vendor toctrees. - Retitle misc/checksum.rst "Checksums" and declare the three checksum packages under it, as pcap.rst does for the pcap packages; the IP pseudo-header and Internet checksum become its sections. - const/tls.rst: both enumerations are generated by the TLS crawlers, no longer hand-curated. - Add test_docs_module_pages_2559_unit.py, pinning documentation.rst's rule that every module outside NotImplemented/ has a directive, and cite it there. Docs tests and a nitpicky partial build of the touched pages pass. --- .../conventions/documentation.rst | 3 + docs/source/pcapkit/const/index.rst | 1 + docs/source/pcapkit/const/linux.rst | 31 ++++++++ docs/source/pcapkit/const/tls.rst | 8 +- .../pcapkit/protocols/misc/checksum.rst | 17 +++- docs/source/pcapkit/vendor/index.rst | 2 + docs/source/pcapkit/vendor/sslv2.rst | 61 ++++++++++++++ docs/source/pcapkit/vendor/tls.rst | 50 ++++++++++++ .../test_docs_module_pages_2559_unit.py | 79 +++++++++++++++++++ 9 files changed, 247 insertions(+), 5 deletions(-) create mode 100644 docs/source/pcapkit/const/linux.rst create mode 100644 docs/source/pcapkit/vendor/sslv2.rst create mode 100644 docs/source/pcapkit/vendor/tls.rst create mode 100644 tests/project/test_docs_module_pages_2559_unit.py diff --git a/docs/source/contributing/conventions/documentation.rst b/docs/source/contributing/conventions/documentation.rst index 5c62de565c..dc4d6a7d9a 100644 --- a/docs/source/contributing/conventions/documentation.rst +++ b/docs/source/contributing/conventions/documentation.rst @@ -297,6 +297,9 @@ worth stating because the opposite is easy to assume -- measured on ``1.5.0b8``, is in the source distribution *and* in the wheel, and each imports as a namespace-package submodule. What they are not is a *package*: none of those directories carries an :file:`__init__.py`, so ``find_packages`` omits all of them. +:file:`tests/project/test_docs_module_pages_2559_unit.py` fails on a module with no +``module``, ``currentmodule`` or ``automodule`` directive, and on a placeholder that +gains one. When something is removed, its documentation entry goes with it -- carrying a deprecation note where a user could have depended on the thing, and deleted outright diff --git a/docs/source/pcapkit/const/index.rst b/docs/source/pcapkit/const/index.rst index e65966dfb5..2535c35fdd 100644 --- a/docs/source/pcapkit/const/index.rst +++ b/docs/source/pcapkit/const/index.rst @@ -70,6 +70,7 @@ Link Layer arp l2tp + linux vlan Internet Layer diff --git a/docs/source/pcapkit/const/linux.rst b/docs/source/pcapkit/const/linux.rst new file mode 100644 index 0000000000..b332b35c9d --- /dev/null +++ b/docs/source/pcapkit/const/linux.rst @@ -0,0 +1,31 @@ +==================================== +Linux-Specific Constant Enumerations +==================================== + +.. module:: pcapkit.const.linux + +This module contains all constant enumerations of the Linux-specific +encapsulations, e.g. :class:`~pcapkit.protocols.link.linux_sll.LinuxSLL`. +Available enumerations include: + +.. list-table:: + + * - :class:`ARPHRD ` + - Linux ARP Hardware Types [*]_ + +ARP Hardware Types +================== + +.. module:: pcapkit.const.linux.arphrd + +This module contains the constant enumeration for **Linux ARP Hardware Types**, +which is automatically generated from :class:`pcapkit.vendor.linux.arphrd.ARPHRD`. + +.. autoclass:: pcapkit.const.linux.arphrd.ARPHRD + :members: + :undoc-members: + :show-inheritance: + +.. rubric:: Footnotes + +.. [*] https://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git/tree/include/uapi/linux/if_arp.h diff --git a/docs/source/pcapkit/const/tls.rst b/docs/source/pcapkit/const/tls.rst index 01f8e46405..5d838df110 100644 --- a/docs/source/pcapkit/const/tls.rst +++ b/docs/source/pcapkit/const/tls.rst @@ -25,8 +25,7 @@ TLS/DTLS Content Types .. module:: pcapkit.const.tls.content_type This module contains the constant enumeration for **TLS/DTLS Content Types**, -hand-curated from IANA's ``TLS ContentType`` registry rather than generated by -a :class:`~pcapkit.vendor.default.Vendor` crawler. +which is automatically generated from :class:`pcapkit.vendor.tls.content_type.ContentType`. .. autoclass:: pcapkit.const.tls.content_type.ContentType :members: @@ -39,8 +38,9 @@ TLS/DTLS HandshakeType .. module:: pcapkit.const.tls.handshake_type This module contains the constant enumeration for **TLS/DTLS HandshakeType**, -hand-curated from IANA's ``TLS HandshakeType`` registry, including the -DTLS-only messages :rfc:`9147#section-5.2` adds to it. +which is automatically generated from +:class:`pcapkit.vendor.tls.handshake_type.HandshakeType`. It includes the +DTLS-only messages :rfc:`9147#section-5.2` adds to the registry. .. autoclass:: pcapkit.const.tls.handshake_type.HandshakeType :members: diff --git a/docs/source/pcapkit/protocols/misc/checksum.rst b/docs/source/pcapkit/protocols/misc/checksum.rst index 6f52a000d8..1ec7f15b08 100644 --- a/docs/source/pcapkit/protocols/misc/checksum.rst +++ b/docs/source/pcapkit/protocols/misc/checksum.rst @@ -1,3 +1,18 @@ +========= +Checksums +========= + +.. module:: pcapkit.protocols.misc.checksum +.. module:: pcapkit.protocols.data.misc.checksum +.. module:: pcapkit.protocols.schema.misc.checksum + +:mod:`pcapkit.protocols.misc.checksum` contains the pseudo-header that +upper-layer checksums cover, +:class:`~pcapkit.protocols.misc.checksum.ip_pseudo.IP_Pseudo`, and in +:mod:`~pcapkit.protocols.misc.checksum.checksum` what the one's-complement +checksums share, such as +:class:`~pcapkit.protocols.misc.checksum.checksum.ChecksumStatus`. + IP Pseudo-Header ================ @@ -85,7 +100,7 @@ Data Models :show-inheritance: Internet Checksum ------------------ +================= .. module:: pcapkit.protocols.misc.checksum.checksum diff --git a/docs/source/pcapkit/vendor/index.rst b/docs/source/pcapkit/vendor/index.rst index e858ad44b6..f5ec23c922 100644 --- a/docs/source/pcapkit/vendor/index.rst +++ b/docs/source/pcapkit/vendor/index.rst @@ -83,6 +83,8 @@ Application Layer http ngap ospf + sslv2 + tls Miscellaneous ------------- diff --git a/docs/source/pcapkit/vendor/sslv2.rst b/docs/source/pcapkit/vendor/sslv2.rst new file mode 100644 index 0000000000..7c2c364386 --- /dev/null +++ b/docs/source/pcapkit/vendor/sslv2.rst @@ -0,0 +1,61 @@ +=================================================================== +:class:`~pcapkit.protocols.application.sslv2.SSLv2` Vendor Crawlers +=================================================================== + +.. module:: pcapkit.vendor.sslv2 + +This module contains all vendor crawlers of +:class:`~pcapkit.protocols.application.sslv2.SSLv2` implementations. Available +vendor crawlers include: + +.. list-table:: + + * - :class:`SSLv2_HandshakeType ` + - SSLv2 Handshake Message Type [*]_ + * - :class:`SSLv2_Version ` + - SSLv2 Protocol Version [*]_ + +.. versionadded:: 1.6.0 + +SSLv2 Handshake Message Type +============================ + +.. module:: pcapkit.vendor.sslv2.handshake_type + +This module contains the vendor crawler for **SSLv2 Handshake Message Type**, +which is automatically generating :class:`pcapkit.const.sslv2.handshake_type.HandshakeType`. + +.. note:: + + This crawler does not crawl. Its source is the expired SSLv2 draft, not a + live registry, so the data is maintained by hand in the ``DATA`` mapping of + :mod:`pcapkit.vendor.sslv2.handshake_type`, and the class defines no + ``LINK``. + +.. autoclass:: pcapkit.vendor.sslv2.handshake_type.HandshakeType + :members: FLAG + :show-inheritance: + +SSLv2 Protocol Version +====================== + +.. module:: pcapkit.vendor.sslv2.version + +This module contains the vendor crawler for **SSLv2 Protocol Version**, +which is automatically generating :class:`pcapkit.const.sslv2.version.Version`. + +.. note:: + + This crawler does not crawl, for the same reason + :class:`~pcapkit.vendor.sslv2.handshake_type.HandshakeType` does: the data + is maintained by hand in the ``DATA`` mapping of + :mod:`pcapkit.vendor.sslv2.version`, and the class defines no ``LINK``. + +.. autoclass:: pcapkit.vendor.sslv2.version.Version + :members: FLAG + :show-inheritance: + +.. rubric:: Footnotes + +.. [*] https://datatracker.ietf.org/doc/html/draft-hickman-netscape-ssl-00 +.. [*] https://datatracker.ietf.org/doc/html/draft-hickman-netscape-ssl-00 diff --git a/docs/source/pcapkit/vendor/tls.rst b/docs/source/pcapkit/vendor/tls.rst new file mode 100644 index 0000000000..abc05c28b6 --- /dev/null +++ b/docs/source/pcapkit/vendor/tls.rst @@ -0,0 +1,50 @@ +=============================================================== +:class:`~pcapkit.protocols.application.ssl.SSL` Vendor Crawlers +=============================================================== + +.. module:: pcapkit.vendor.tls + +This module contains the vendor crawlers of the constant enumerations shared by +the record-layer implementations under the +:class:`~pcapkit.protocols.application.ssl.SSL` umbrella -- +:class:`~pcapkit.protocols.application.tls.TLS` (SSLv3 through TLS 1.3) and +:class:`~pcapkit.protocols.application.dtls.DTLS`. Available vendor crawlers +include: + +.. list-table:: + + * - :class:`TLS_ContentType ` + - TLS/DTLS Content Types [*]_ + * - :class:`TLS_HandshakeType ` + - TLS/DTLS HandshakeType [*]_ + +.. versionadded:: 1.6.0 + +TLS/DTLS Content Types +====================== + +.. module:: pcapkit.vendor.tls.content_type + +This module contains the vendor crawler for **TLS/DTLS Content Types**, +which is automatically generating :class:`pcapkit.const.tls.content_type.ContentType`. + +.. autoclass:: pcapkit.vendor.tls.content_type.ContentType + :members: FLAG, LINK + :show-inheritance: + +TLS/DTLS HandshakeType +====================== + +.. module:: pcapkit.vendor.tls.handshake_type + +This module contains the vendor crawler for **TLS/DTLS HandshakeType**, +which is automatically generating :class:`pcapkit.const.tls.handshake_type.HandshakeType`. + +.. autoclass:: pcapkit.vendor.tls.handshake_type.HandshakeType + :members: FLAG, LINK + :show-inheritance: + +.. rubric:: Footnotes + +.. [*] https://www.iana.org/assignments/tls-parameters/tls-parameters.xhtml#tls-parameters-5 +.. [*] https://www.iana.org/assignments/tls-parameters/tls-parameters.xhtml#tls-parameters-7 diff --git a/tests/project/test_docs_module_pages_2559_unit.py b/tests/project/test_docs_module_pages_2559_unit.py new file mode 100644 index 0000000000..2eefddc72d --- /dev/null +++ b/tests/project/test_docs_module_pages_2559_unit.py @@ -0,0 +1,79 @@ +# -*- coding: utf-8 -*- +"""Pins that every importable shipped module has a documentation entry (#2559). + +The *Resolvable Targets* section of +:file:`docs/source/contributing/conventions/documentation.rst` rules that every +importable module under :file:`pcapkit/` is documented, the placeholder sources +under :file:`pcapkit/protocols/*/NotImplemented/` being the one exception. + +* :class:`ModulePageTests` -- every module outside the exception is named by a + ``module``, ``currentmodule`` or ``automodule`` directive under + :file:`docs/source/`, and no module inside it is. + +The check is textual and imports nothing. + +""" + +from __future__ import annotations + +import pathlib +import re +import unittest + +#: Test tier (#1958): reads the package tree and the docs pages, and imports nothing. +__tier__ = 'LATEST' + +ROOT = pathlib.Path(__file__).resolve().parents[2] + +#: The package whose modules must be documented, and the pages documenting them. +PACKAGE = ROOT / 'pcapkit' +DOCS = ROOT / 'docs' / 'source' + +#: The directory name of the placeholder sources the convention exempts. +EXEMPT_DIR = 'NotImplemented' + +#: A directive that names a module, capturing the dotted name. +DIRECTIVE = re.compile(r'^\.\. +(?:py:)?(?:module|currentmodule|automodule):: +(\S+)', re.M) + + +def _modules() -> 'dict[str, bool]': + """Every module under :data:`PACKAGE`, mapped to whether it is in the exempt set.""" + found = {} # type: dict[str, bool] + for path in PACKAGE.rglob('*.py'): + rel = path.relative_to(ROOT).with_suffix('') + if '__pycache__' in rel.parts: + continue + parts = rel.parts[:-1] if rel.name == '__init__' else rel.parts + found['.'.join(parts)] = EXEMPT_DIR in parts + return found + + +def _documented() -> 'set[str]': + """Every dotted name a module directive under :data:`DOCS` declares.""" + names = set() # type: set[str] + for page in DOCS.rglob('*.rst'): + names.update(DIRECTIVE.findall(page.read_text(encoding='utf-8'))) + return names + + +class ModulePageTests(unittest.TestCase): + """Every shipped module has an entry, and the exempt set has none.""" + + modules = _modules() + documented = _documented() + + def test_every_module_is_documented(self) -> 'None': + """A module outside the exception with no directive names the page it needs.""" + missing = sorted(name for name, exempt in self.modules.items() + if not exempt and name not in self.documented) + self.assertEqual(missing, [], 'add a page or a module directive for each of these') + + def test_exempt_modules_have_no_entry(self) -> 'None': + """The exception exists, and documenting one of its modules breaks the convention's claim.""" + exempt = {name for name, flag in self.modules.items() if flag} + self.assertTrue(exempt, f'no module under a {EXEMPT_DIR}/ directory; update the convention') + self.assertEqual(sorted(exempt & self.documented), []) + + +if __name__ == '__main__': + unittest.main() From f7232f6a86e69e1ea626bad99399b9f1ac592f0c Mon Sep 17 00:00:00 2001 From: Jarry Shaw Date: Sun, 1 Nov 2026 11:45:49 -0500 Subject: [PATCH 2/2] docs(link): leave ARPHRD's entry to the const page (#2559) - linux_sll.rst's "Hardware Types" autoclass rendered pcapkit.const.linux.arphrd.ARPHRD a second time now that const/linux.rst documents it, so a serial nitpicky build reported duplicate object descriptions. The section now points to the const page, the single home every other const registry has. Docs tests pass; a serial nitpicky build has no duplicate warnings. --- docs/source/pcapkit/protocols/link/linux_sll.rst | 7 ++----- 1 file changed, 2 insertions(+), 5 deletions(-) diff --git a/docs/source/pcapkit/protocols/link/linux_sll.rst b/docs/source/pcapkit/protocols/link/linux_sll.rst index e49f07dbd9..e3d4a2bede 100644 --- a/docs/source/pcapkit/protocols/link/linux_sll.rst +++ b/docs/source/pcapkit/protocols/link/linux_sll.rst @@ -50,11 +50,8 @@ Auxiliary Constants Hardware Types -------------- -The ``arphrd_type`` keys of ``LinuxSLL.__proto__`` are named by the enumeration below. - -.. autoclass:: pcapkit.const.linux.arphrd.ARPHRD - :members: - :show-inheritance: +The ``arphrd_type`` keys of ``LinuxSLL.__proto__`` are named by +:class:`~pcapkit.const.linux.arphrd.ARPHRD`. .. _linux-sll-labels: