From d6361ffdcc9dc7c69c973eea55ee372b35150a71 Mon Sep 17 00:00:00 2001 From: Jarry Shaw Date: Thu, 15 Oct 2026 18:47:09 -0400 Subject: [PATCH] docs(docs): second whole-repo pass over the non-API docs and indexes (#1103) - Accuracy: the protocol hierarchy graph puts IPsec under Internet, not IP, and draws IPv6_Ext as the base of every IPv6 extension header, AH, ESP and HIP included; ext.rst's shipped-protocol table gains its IPv6_Ext row. - Accuracy: SeekableReader has 14 positional-only methods, not 13 (_fill, #1586); mint-criterion's AppType._missing_ pointer moves to apptype.py:2958; the pcapkit-vendor help transcript reads "options:", as argparse prints it on every supported Python. - Directives: versionchanged 1.5.0 on the CLI section, for -P and -L taking effect and -L's closed set of layer names (#356). - Conventions: documentation.rst records that a hand-written .. data:: or .. function:: takes the bare name under its .. module::, with :module: where the object lives elsewhere (#1775). - Toctrees: dumpkit lists common, its base-class page, first, as every sibling index does. tests/project: 950 passed, 1 skipped. Refs #1103 --- .../contributing/conventions/documentation.rst | 9 +++++++++ .../contributing/conventions/mint-criterion.rst | 2 +- docs/source/ext.rst | 2 ++ docs/source/index.rst | 2 +- docs/source/pcapkit/dumpkit/index.rst | 2 +- docs/source/pcapkit/index.rst | 6 ++++++ docs/source/pcapkit/protocols/index.rst | 14 ++++++++------ docs/source/pcapkit/vendor/index.rst | 2 +- 8 files changed, 29 insertions(+), 10 deletions(-) diff --git a/docs/source/contributing/conventions/documentation.rst b/docs/source/contributing/conventions/documentation.rst index 04315fd9cb..e77da36e70 100644 --- a/docs/source/contributing/conventions/documentation.rst +++ b/docs/source/contributing/conventions/documentation.rst @@ -267,6 +267,15 @@ settled this on :issue:`719` found exactly one, and repeating it is cheap: [ -f "$path.py" ] || [ -f "$path/__init__.py" ] || echo "dangling: $path" done +**Under a** ``.. module::``, **a hand-written** ``.. data::`` **or** ``.. function::`` +**takes the bare name.** The module directive already supplies the prefix, so +``.. data:: pcapkit.x._T`` under ``.. module:: pcapkit.x`` registers +``pcapkit.x.pcapkit.x._T``, which no reference resolves to exactly. Where the object +lives in a module other than the current one, a ``:module:`` option names it, as the +``LINKTYPE`` entry on :doc:`/pcapkit/protocols/link/index` does. :issue:`1775` found 44 +directives spelled the long way, which left seven TypeVar references ambiguous; +:file:`tests/project/test_docs_ambiguous_xrefs_1775_unit.py` fails on the next one. + **Every importable shipped module is documented, with one deliberate exception.** The 33 modules under :file:`pcapkit/protocols/*/NotImplemented/` are the set with no entry: placeholder sources for dissectors nobody has written yet, carrying no class a reader diff --git a/docs/source/contributing/conventions/mint-criterion.rst b/docs/source/contributing/conventions/mint-criterion.rst index 048e55b5c4..225dae6bca 100644 --- a/docs/source/contributing/conventions/mint-criterion.rst +++ b/docs/source/contributing/conventions/mint-criterion.rst @@ -10,7 +10,7 @@ a ``_missing_`` override, which decides what happens when a value has no member. MRO, so they carry no declared-but-unassigned range to resolve. 121 define one themselves; the other four are the transport subclasses of :class:`~pcapkit.const.reg.apptype.apptype.AppType`, which inherit -``AppType._missing_`` (:file:`pcapkit/const/reg/apptype/apptype.py:2936`). Three +``AppType._missing_`` (:file:`pcapkit/const/reg/apptype/apptype.py:2958`). Three behaviours follow from it, and which one a given range gets is a **design decision, not a style preference**: diff --git a/docs/source/ext.rst b/docs/source/ext.rst index c0dafcaa5a..5af2bd1ba7 100644 --- a/docs/source/ext.rst +++ b/docs/source/ext.rst @@ -44,6 +44,8 @@ The protocol classes :mod:`pcapkit` ships: + + +-----------------------+-------------------------------------------------------------+ | | | :class:`pcapkit.protocols.internet.ipv6.IPv6` | + + +-----------------------+-------------------------------------------------------------+ +| | | | :class:`pcapkit.protocols.internet.ipv6_ext.IPv6_Ext` | ++ + + +-------------------------------------------------------------+ | | | | :class:`pcapkit.protocols.internet.ipv6_frag.IPv6_Frag` | + + + +-------------------------------------------------------------+ | | | | :class:`pcapkit.protocols.internet.ipv6_opts.IPv6_Opts` | diff --git a/docs/source/index.rst b/docs/source/index.rst index 5cce1e487e..f0ca1a9344 100644 --- a/docs/source/index.rst +++ b/docs/source/index.rst @@ -257,7 +257,7 @@ Installation is intent rather than something that works. ``bpc-poseur`` 0.4.3.post1 crashes on positional-only parameters declared on a *method* rather than a plain function, and exits 0 so the build does not notice; such methods -- including - the 13 on :class:`~pcapkit.corekit.io.SeekableReader`, plus a dozen more across + the 14 on :class:`~pcapkit.corekit.io.SeekableReader`, plus a dozen more across the protocols, foundation, dumpkit and corekit modules -- then survive into the installed package and ``import pcapkit`` fails with :exc:`SyntaxError`. diff --git a/docs/source/pcapkit/dumpkit/index.rst b/docs/source/pcapkit/dumpkit/index.rst index 7d7904609a..16b903a642 100644 --- a/docs/source/pcapkit/dumpkit/index.rst +++ b/docs/source/pcapkit/dumpkit/index.rst @@ -10,9 +10,9 @@ alike those in :mod:`dictdumper`. .. toctree:: :maxdepth: 2 + common pcap null - common Every dumper class is a :class:`dictdumper.dumper.Dumper` subclass, responsible for writing parsed packet data into a formatted output file. The class diff --git a/docs/source/pcapkit/index.rst b/docs/source/pcapkit/index.rst index acfd295566..d316cb1f92 100644 --- a/docs/source/pcapkit/index.rst +++ b/docs/source/pcapkit/index.rst @@ -120,6 +120,12 @@ Command Line Tool The name of buffer storage file. If `--buffer-save` is set and this omits, it will be automatically assigned. +.. versionchanged:: 1.5.0 + + ``-P`` and ``-L`` stop the extraction where they say, which 1.4.x ignored, and + ``-L`` accepts only ``link``, ``internet``, ``transport``, ``application`` or + ``none``, in any case (:issue:`356`). + Environment Variables ===================== diff --git a/docs/source/pcapkit/protocols/index.rst b/docs/source/pcapkit/protocols/index.rst index 858ea81977..48f4c783d2 100644 --- a/docs/source/pcapkit/protocols/index.rst +++ b/docs/source/pcapkit/protocols/index.rst @@ -43,18 +43,18 @@ from given information. The class hierarchy of :mod:`pcapkit.protocols`: end subgraph internet [Internet Layer] - Internet --> HIP & IPX & IP & ipv6ext + Internet --> IPX & IP & IPsec & IPv6_Ext subgraph ip [IP Family] - IP --> IPv4 & IPv6 & IPsec + IP --> IPv4 & IPv6 + end - subgraph ipsec [IPsec Family] - IPsec --> AH & ESP - end + subgraph ipsec [IPsec Family] + IPsec --> AH & ESP end subgraph ipv6ext [IPv6 Extension Header] - IPv6-Frag & IPv6-Opts & IPv6-Route & HOPOPT & MH + IPv6_Ext --> IPv6-Frag & IPv6-Opts & IPv6-Route & HOPOPT & MH & HIP end end @@ -95,6 +95,7 @@ from given information. The class hierarchy of :mod:`pcapkit.protocols`: B --> Header & Frame & PCAPNG & Raw & NoPayload Raw --> FTP_DATA ARP --> RARP + IPv6_Ext --> AH & ESP B --> C(Protocol) C --> D([user customisation ...]) @@ -124,6 +125,7 @@ from given information. The class hierarchy of :mod:`pcapkit.protocols`: click IPsec "/pcapkit/protocols/internet/ipsec.html#pcapkit.protocols.internet.ipsec.IPsec" click IPv4 "/pcapkit/protocols/internet/ipv4.html#pcapkit.protocols.internet.ipv4.IPv4" click IPv6 "/pcapkit/protocols/internet/ipv6.html#pcapkit.protocols.internet.ipv6.IPv6" + click IPv6_Ext "/pcapkit/protocols/internet/ipv6_ext.html#pcapkit.protocols.internet.ipv6_ext.IPv6_Ext" click IPv6-Frag "/pcapkit/protocols/internet/ipv6_frag.html#pcapkit.protocols.internet.ipv6_frag.IPv6_Frag" click IPv6-Opts "/pcapkit/protocols/internet/ipv6_opts.html#pcapkit.protocols.internet.ipv6_opts.IPv6_Opts" click IPv6-Route "/pcapkit/protocols/internet/ipv6_route.html#pcapkit.protocols.internet.ipv6_route.IPv6_Route" diff --git a/docs/source/pcapkit/vendor/index.rst b/docs/source/pcapkit/vendor/index.rst index 6d897a2292..f860acc7fb 100644 --- a/docs/source/pcapkit/vendor/index.rst +++ b/docs/source/pcapkit/vendor/index.rst @@ -92,6 +92,6 @@ constant enumerations. positional arguments: target update targets, supply none to update all - optional arguments: + options: -h, --help show this help message and exit -V, --version show program's version number and exit