From 8a7b5625f7eb5539ddc725c832220421a23f9437 Mon Sep 17 00:00:00 2001 From: Jarry Shaw Date: Wed, 30 Sep 2026 22:21:02 -0400 Subject: [PATCH] docs: tighten demo.rst and the docs landing page (#719) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - demo.rst: cut hedging from the Basic Samples lead-in and fix "has two different access" in the CLI section. - demo.rst: correct the CLI transcripts at six sites. All three examples showed "🚨Loading"/"🍺Report" with no space; the real output has one, since pcapkit/__main__.py:135,143 emojizes ":police_car_light: Loading file ..." with the space inside the f-string. - index.rst: tighten the About comparison, the Engine Comparison opening and the pypcap/pcap_ct exclusivity note; drop "introduced" and "By now", which date prose that describes the present. - index.rst: fix "foundamental", "the gi repository", and a missing relative pronoun in the jspcapy note. - index.rst: restate the speed claim against the table it cites -- pcapkit's own engine is slower than five of the six third-party engines and faster than pyshark, which "not enough comparing to other popular extraction engines" did not say. Every toctree entry, every .. deprecated:: directive and every design-rationale note is untouched. All three demo.rst examples and all three CLI invocations were re-run against examples/captures/in.pcap. tests/project/test_conventions_doc_claims.py and its two siblings: 44 tests, 1 skipped, 0 failed. --- docs/source/demo.rst | 17 ++++++++--------- docs/source/index.rst | 44 +++++++++++++++++++++---------------------- 2 files changed, 29 insertions(+), 32 deletions(-) diff --git a/docs/source/demo.rst b/docs/source/demo.rst index c7fb9580f7..395a4f8ffc 100644 --- a/docs/source/demo.rst +++ b/docs/source/demo.rst @@ -4,8 +4,7 @@ How to ... Basic Samples ------------- -:mod:`pcapkit` is quite easy to use, with simply three verbs as -its main interface. Several scenarios are shown as below. +:mod:`pcapkit` is built around three verbs. A few common scenarios: 1. extract a PCAP file and dump the result to a specific file (with no reassembly) @@ -50,7 +49,7 @@ its main interface. Several scenarios are shown as below. CLI Samples ----------- -The CLI (command line interface) of :mod:`pcapkit` has two different access. +:mod:`pcapkit`'s CLI (command line interface) can be reached two ways. * through console scripts @@ -70,14 +69,14 @@ Here are some usage samples: .. code-block:: shell $ pcapkit-cli in --auto-extension --format plist --verbose - 🚨Loading file 'in.pcap' + 🚨 Loading file 'in.pcap' Frame 1: Ethernet:IPv6:IPv6_ICMP Frame 2: Ethernet:IPv6:IPv6_ICMP Frame 3: Ethernet:IPv4:TCP Frame 4: Ethernet:IPv4:TCP Frame 5: Ethernet:IPv4:TCP Frame 6: Ethernet:IPv4:UDP:Raw - 🍺Report file stored in 'out.plist' + 🍺 Report file stored in 'out.plist' 2. export to a JSON file @@ -91,27 +90,27 @@ Here are some usage samples: .. code-block:: shell $ pcapkit-cli in --auto-extension --output out.json --format json --verbose - 🚨Loading file 'in.pcap' + 🚨 Loading file 'in.pcap' Frame 1: Ethernet:IPv6:IPv6_ICMP Frame 2: Ethernet:IPv6:IPv6_ICMP Frame 3: Ethernet:IPv4:TCP Frame 4: Ethernet:IPv4:TCP Frame 5: Ethernet:IPv4:TCP Frame 6: Ethernet:IPv4:UDP:Raw - 🍺Report file stored in 'out.json' + 🍺 Report file stored in 'out.json' 3. export to a text tree view file (without extension autocorrect) .. code-block:: shell $ pcapkit-cli in.pcap --output out.txt --format tree --verbose - 🚨Loading file 'in.pcap' + 🚨 Loading file 'in.pcap' Frame 1: Ethernet:IPv6:IPv6_ICMP Frame 2: Ethernet:IPv6:IPv6_ICMP Frame 3: Ethernet:IPv4:TCP Frame 4: Ethernet:IPv4:TCP Frame 5: Ethernet:IPv4:TCP Frame 6: Ethernet:IPv4:UDP:Raw - 🍺Report file stored in 'out.txt' + 🍺 Report file stored in 'out.txt' .. _Xcode: https://developer.apple.com/xcode diff --git a/docs/source/index.rst b/docs/source/index.rst index 91b1fb0a99..aa09a37953 100644 --- a/docs/source/index.rst +++ b/docs/source/index.rst @@ -48,8 +48,8 @@ About .. note:: - There is a project called |jspcapy|_ works on :mod:`pcapkit`, which is a - command line tool for PCAP extraction. + There is a project called |jspcapy|_ that works on :mod:`pcapkit`, which is + a command line tool for PCAP extraction. .. |jspcapy| replace:: ``jspcapy`` .. _jspcapy: https://github.com/JarryShaw/jspcapy @@ -59,11 +59,10 @@ About The |jspcapy|_ project is deprecated and has been merged into the :mod:`PyPCAPKit ` project as its CLI support. -Unlike popular PCAP file extractors, such as :mod:`Scapy `, -:mod:`dpkt `, `PyShark`_, and etc, :mod:`pcapkit` is -designed to be much more comprehensive, which means it is able to provide -more detailed information about the packet, as well as a more *Pythonic* -interface for users to interact with. +Unlike popular PCAP extractors such as :mod:`Scapy `, +:mod:`dpkt ` and `PyShark`_, :mod:`pcapkit` aims to be more +comprehensive: more detailed packet information, and a more *Pythonic* +interface. ---------------- Module Structure @@ -80,7 +79,7 @@ In :mod:`pcapkit`, all files can be described as following eight parts. Synthesises file I/O and protocol analysis, coordinates information exchange in all network layers, as well as - provides the foundamental functions for :mod:`pcapkit`. + provides the fundamental functions for :mod:`pcapkit`. - Protocols (:mod:`pcapkit.protocols`) @@ -114,17 +113,16 @@ In :mod:`pcapkit`, all files can be described as following eight parts. Engine Comparison ----------------- -Due to the general overhead of :mod:`pcapkit`, its extraction procedure takes -around *0.2* milliseconds per packet, which is already impressive but not enough -comparing to other popular extraction engines available on the market, given the -fact that :mod:`pcapkit` is a **comprehensive** packet processing module. +Being a **comprehensive** packet processor costs speed: :mod:`pcapkit`'s own +engine takes about *0.2* milliseconds per packet, slower than most of the +third-party engines below. -Additionally, :mod:`pcapkit` introduced alternative extraction engines to -accelerate this procedure. By now :mod:`pcapkit` supports `Scapy`_, `DPKT`_, -`PyShark`_, `PyPCAP`_, `pcap-ct`_ and `PyPCAPFile`_, selected through -``engine='scapy'``, ``'dpkt'``, ``'pyshark'``, ``'pypcap'``, ``'pcap_ct'`` and -``'pypcapfile'`` respectively; ``engine='default'`` (also spelled ``'pcapkit'``) -is :mod:`pcapkit`'s own parser and the only one with no third-party requirement. +:mod:`pcapkit` also supports alternative extraction engines for speed: +`Scapy`_, `DPKT`_, `PyShark`_, `PyPCAP`_, `pcap-ct`_ and `PyPCAPFile`_, +selected through ``engine='scapy'``, ``'dpkt'``, ``'pyshark'``, ``'pypcap'``, +``'pcap_ct'`` and ``'pypcapfile'`` respectively; ``engine='default'`` (also +spelled ``'pcapkit'``) is :mod:`pcapkit`'s own parser and the only one with no +third-party requirement. `PyPCAP`_ and `pcap-ct`_ are two independent distributions of the same :manpage:`libpcap(3)` interface and both install a top-level :mod:`pcap` module, @@ -175,9 +173,9 @@ Engine 3.10 3.11 3.12 3.13 3.14 3.15 [*]_ ``pypcap`` and ``pypcapfile`` stop at 3.11, and ``pyshark`` at 3.13, for the reasons under `Engine prerequisites`_. **Python 3.11 is the last version on which -every engine can run** -- and even there ``pypcap`` and ``pcap_ct`` are mutually -exclusive, since both provide the :mod:`pcap` module, so no single environment ever -has all seven at once. +every engine can run** -- and even there ``pypcap`` and ``pcap_ct`` remain +mutually exclusive for the reason given above, so no single environment ever has +all seven at once. Test Environment ---------------- @@ -255,13 +253,13 @@ Installation 3.8 and 3.9 are end-of-life and best-effort. Individual *engines* also stop earlier than the library does; see `Engine prerequisites`_. -Simply run the following to install the current version from PyPI: +Run the following to install the current version from PyPI: .. code-block:: shell pip install pypcapkit -Or install the latest version from the gi repository: +Or install the latest version from the git repository: .. code-block:: shell