docs(pcapkit): give every undocumented shipped module a page

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

docs/source/pcapkit/const/index.rst

@@ -70,6 +70,7 @@ Link Layer
 
    arp
    l2tp
+   linux
    vlan
 
 Internet Layer

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 <pcapkit.const.linux.arphrd.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

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:

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:
 

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
 

docs/source/pcapkit/vendor/index.rst

@@ -83,6 +83,8 @@ Application Layer
    http
    ngap
    ospf
+   sslv2
+   tls
 
 Miscellaneous
 -------------

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 <pcapkit.vendor.sslv2.handshake_type.HandshakeType>`
+     - SSLv2 Handshake Message Type [*]_
+   * - :class:`SSLv2_Version <pcapkit.vendor.sslv2.version.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

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 <pcapkit.vendor.tls.content_type.ContentType>`
+     - TLS/DTLS Content Types [*]_
+   * - :class:`TLS_HandshakeType <pcapkit.vendor.tls.handshake_type.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

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()