From c23963171d3a9358f9a49c18d6bbdedc808a6098 Mon Sep 17 00:00:00 2001 From: Jarry Date: Tue, 29 Sep 2026 01:32:54 -0400 Subject: [PATCH] docs: move the process pages out of the docs top level (#901) * `git mv` conventions.rst, releasing.rst, testing.rst, workflows.rst and pep.rst into a new `docs/source/contributing/` subdirectory. Named explicitly by the owner (conventions, releasing, testing); workflows and pep join them since both are contributor/process-facing (CI graph and the roadmap) rather than library-usage docs. demo.rst, ext.rst and changelog.rst stay -- they're what a reader of the library, not a contributor, wants at the root; index.rst is the root document. * Update `docs/source/index.rst`'s toctree to the new paths, in its own block. This moves `changelog` from last to third in the rendered nav. * Fix the one cross-tree `:doc:` reference the move broke: `pcapkit/protocols/internet/mh.rst` pointed at `/pep`, now `/contributing/pep`. Eleven `:doc:` references in pep.rst gained the leading `/` its new directory needs -- ten into `pcapkit/`, plus one to `/ext`, a page that stays at the root. The relative sibling references that genuinely needed no change are in releasing.rst (-> `pep`) and workflows.rst (-> `releasing`, five times), and they survive only because those two pages moved together; leaving either behind would have broken all six. * Update the plain-text path mentions that don't resolve as Sphinx roles: CONTRIBUTING.md, README.md's rendered-doc link, a workflow comment, and four docstring/comment references to conventions.rst under tests/. Sphinx build: 58 warnings, unchanged from the 58-warning baseline (fresh BUILDDIR, doc root confirmed as this worktree via PYTHONPATH). `util/ changelog_md.py --check` exits 0, unaffected since changelog.rst didn't move. The real setuptools sdist ships the same 928 entries before and after, with identical `tar tzf` listings; six of those files do change content -- README.md, both PKG-INFO copies and the three tests/ modules, since MANIFEST.in's `prune test` does not match `tests/` -- all of it comment, docstring and URL text. tests/project/ (178 tests) and the touched unit tests all pass. Pure move plus reference fixes, no new logic, so no coverage change is expected. --- .github/workflows/create-release.yml | 2 +- CONTRIBUTING.md | 6 ++--- README.md | 2 +- .../source/{ => contributing}/conventions.rst | 0 docs/source/{ => contributing}/pep.rst | 22 +++++++++---------- docs/source/{ => contributing}/releasing.rst | 0 docs/source/{ => contributing}/testing.rst | 0 docs/source/{ => contributing}/workflows.rst | 0 docs/source/index.rst | 14 +++++++----- docs/source/pcapkit/protocols/internet/mh.rst | 2 +- tests/corekit/test_enum_lookup_base_unit.py | 2 +- .../test_fields_numbers_unassigned_enum.py | 2 +- tests/protocols/misc/test_pcapng_unit.py | 4 ++-- 13 files changed, 30 insertions(+), 26 deletions(-) rename docs/source/{ => contributing}/conventions.rst (100%) rename docs/source/{ => contributing}/pep.rst (98%) rename docs/source/{ => contributing}/releasing.rst (100%) rename docs/source/{ => contributing}/testing.rst (100%) rename docs/source/{ => contributing}/workflows.rst (100%) diff --git a/.github/workflows/create-release.yml b/.github/workflows/create-release.yml index d3ab4cdf23..bed307727d 100644 --- a/.github/workflows/create-release.yml +++ b/.github/workflows/create-release.yml @@ -47,7 +47,7 @@ concurrency: # ``tag`` and ``pypi`` both carry ``needs: [ github, ... ]``, and ``conda`` needs # ``tag`` and ``github`` too, so nothing downstream of ``github`` can start before # that approval lands, and rejecting it leaves nothing tagged and nothing -# published. See :file:`docs/source/releasing.rst` for the full pipeline and the +# published. See :file:`docs/source/contributing/releasing.rst` for the full pipeline and the # reasoning behind one approval being enough. # # The other three environments keep their names -- ``pypi``'s matters because diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index a48afa206c..aac0279fbd 100755 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -9,14 +9,14 @@ happens after that. - Fork the repository on GitHub. - Read the README for installation and build instructions, and the *Testing* page it links from its - *Documentation* table — `docs/source/testing.rst` — for the test commands. + *Documentation* table — `docs/source/contributing/testing.rst` — for the test commands. - Set up a development environment. `make setup` runs `pipenv install --skip-lock --dev`, and the `Makefile` exports `PIPENV_VENV_IN_PROJECT=1`, so the environment lands in `.venv/` inside the checkout. **Only that environment has the dependencies** — the `make` targets below all run through `pipenv run`, and invoking `pytest` or `sphinx` from a system interpreter will fail on missing imports rather than on anything you changed. -- Looking for something to pick up? `docs/source/pep.rst` — rendered as the *Help Wanted* page — is - the maintained list of open proposals, kept in step with the code. +- Looking for something to pick up? `docs/source/contributing/pep.rst` — rendered as the *Help + Wanted* page — is the maintained list of open proposals, kept in step with the code. - Play with the project, submit bugs, submit patches! ## Contribution flow diff --git a/README.md b/README.md index 2f5b6bd199..6552590e06 100644 --- a/README.md +++ b/README.md @@ -94,7 +94,7 @@ reference for everything below. The pages worth knowing by name: | [Engine comparison](https://jarryshaw.github.io/PyPCAPKit/#engine-comparison) | Which engines exist, which Python versions they run on, and measured speed per packet | | [Engine support](https://jarryshaw.github.io/PyPCAPKit/pcapkit/foundation/engines/index.html) | What each engine does *not* support, and how the gap is surfaced | | [Installation](https://jarryshaw.github.io/PyPCAPKit/#installation) | Extras, engine prerequisites and the local development setup | -| [Testing](https://jarryshaw.github.io/PyPCAPKit/testing.html) | Running the suite, and the sample captures it needs | +| [Testing](https://jarryshaw.github.io/PyPCAPKit/contributing/testing.html) | Running the suite, and the sample captures it needs | | [How to ...](https://jarryshaw.github.io/PyPCAPKit/demo.html) | Worked examples, library and CLI | | [Extensions](https://jarryshaw.github.io/PyPCAPKit/ext.html) | Registering your own protocols, engines and dumpers | diff --git a/docs/source/conventions.rst b/docs/source/contributing/conventions.rst similarity index 100% rename from docs/source/conventions.rst rename to docs/source/contributing/conventions.rst diff --git a/docs/source/pep.rst b/docs/source/contributing/pep.rst similarity index 98% rename from docs/source/pep.rst rename to docs/source/contributing/pep.rst index 7e11d2eeb8..3774c5c10a 100644 --- a/docs/source/pep.rst +++ b/docs/source/contributing/pep.rst @@ -96,7 +96,7 @@ registers considerably more than :rfc:`9260` defines, and the surplus falls through to the generic handlers rather than failing the extraction -- so a capture using one parses, but yields an opaque chunk instead of its fields. As things stand that is 17 of the 30 registered chunk types, 24 of the 32 -chunk parameters and 10 of the 23 error causes; :doc:`pcapkit/const/sctp` +chunk parameters and 10 of the 23 error causes; :doc:`/pcapkit/const/sctp` lists them all. The other thing wanted for SCTP is reassembly, which no protocol beyond IP and @@ -113,7 +113,7 @@ Association is supplied through the protocol keyed :mod:`pcapkit.corekit.context` channel. What is still wanted there is wider algorithm coverage. The two enumerations -under :doc:`pcapkit/const/esp` carry every transform IANA has registered -- 36 +under :doc:`/pcapkit/const/esp` carry every transform IANA has registered -- 36 :class:`~pcapkit.const.esp.cipher.Cipher` members and 15 :class:`~pcapkit.const.esp.integrity.Integrity` members -- but :data:`~pcapkit.protocols.internet.esp.CIPHER_SUITES` and @@ -169,7 +169,7 @@ The sub-registries turned out to be the easy half, as predicted: binding revocation types and triggers, handoff indicators, access network identifier sub-options, flow identification and flow binding sub-options, LMA-controlled MAG parameters, DNS update status, traffic selector formats and QoS attributes were -already generated in full under :doc:`pcapkit/const/mh`, and **no new +already generated in full under :doc:`/pcapkit/const/mh`, and **no new enumeration or vendor crawler was needed**. Two value sets did have to be added to ``mh.py`` itself rather than to :mod:`pcapkit.const.mh`, because IANA registers neither: the localized routing acknowledgment status codes of @@ -275,7 +275,7 @@ Registered, But Not Dissected ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ A different shape of gap from the empty stubs, and easy to miss because nothing -announces it. The :doc:`pcapkit/const/reg` enumerations are complete, but only a +announces it. The :doc:`/pcapkit/const/reg` enumerations are complete, but only a small part of each is bound to a dissector; everything else resolves to :class:`~pcapkit.protocols.misc.raw.Raw`, so the capture parses without complaint and yields nothing useful. @@ -383,7 +383,7 @@ PCAPNG Support **Done.** The builtin default engine parses PCAP-NG files; :class:`~pcapkit.protocols.misc.pcapng.PCAPNG` implements the format, with its -block and option enumerations under :doc:`pcapkit/const/pcapng`. This closes +block and option enumerations under :doc:`/pcapkit/const/pcapng`. This closes the request in `#35 `__, which the thread raised when only PCAP was supported. @@ -474,7 +474,7 @@ with a hard-wired handler. It now provides: flow-tracing setup -- so that ``DEBUG`` explains what PyPCAPKit did with a file without descending into per-field parsing. -See :doc:`pcapkit/utilities/logging` for the configuration recipes, including +See :doc:`/pcapkit/utilities/logging` for the configuration recipes, including the one-line restore of the pre-existing :obj:`sys.stderr` output. One item remains wanted, called out there as deliberately out of scope: @@ -492,7 +492,7 @@ each has a matching :mod:`pcapkit.toolkit` module (:mod:`pcapkit.toolkit.pypcapfile`, :mod:`pcapkit.toolkit.pypcap`), a ``pyproject.toml`` extra (``PyPCAPFile``, which ``all`` includes, and ``PyPCAP``, which it deliberately does not -- see below), docs -under :doc:`pcapkit/foundation/engines/index`, and tests under +under :doc:`/pcapkit/foundation/engines/index`, and tests under ``tests/foundation/engines/`` and ``tests/toolkit/``. Both were verified end-to-end against the sample captures: each agrees with the ``default`` engine on frame count, per-record capture length, timestamp and Ethernet header. @@ -569,7 +569,7 @@ noisily: `pypcap`_ performs no protocol dissection, so it disables reassembly reassembly while keeping IPv4 and TCP. Each gap is announced through an :class:`~pcapkit.utilities.warnings.AttributeWarning` or an outright exception rather than by silently returning nothing -- -:doc:`pcapkit/foundation/engines/index` tabulates them. +:doc:`/pcapkit/foundation/engines/index` tabulates them. Adding a further engine no longer means adding handler methods to :class:`~pcapkit.foundation.extraction.Extractor`, as the thread describes: the @@ -577,7 +577,7 @@ engine interface has been refactored since. A new engine subclasses :class:`pcapkit.foundation.engines.engine.Engine` and implements just two methods, :meth:`~pcapkit.foundation.engines.engine.Engine.run` and :meth:`~pcapkit.foundation.engines.engine.Engine.read_frame`; subclassing -registers it automatically. See :doc:`ext` for a worked example. What does +registers it automatically. See :doc:`/ext` for a worked example. What does still apply is the unified auxiliary tools in :mod:`pcapkit.toolkit`, where each engine has a matching module. @@ -619,7 +619,7 @@ Reassembly Beyond IP and TCP ---------------------------- **Still open**, and newer than the rest of this page -- -:doc:`pcapkit/foundation/reassembly/index` covers three protocols and no more. +:doc:`/pcapkit/foundation/reassembly/index` covers three protocols and no more. IPv4 and IPv6 share the :rfc:`791` procedure, and TCP uses the :rfc:`815` hole-descriptor algorithm, which does handle out-of-order and overlapping segments. SCTP has nothing: a user message split across DATA chunks is never put @@ -774,7 +774,7 @@ Two smaller items in the same subsystem: Reassembly is also unavailable on some engines rather than merely slower, which is worth knowing before benchmarking against them: ``pyshark``, ``pypcap`` and ``pcap_ct`` disable it entirely, and ``pypcapfile`` disables the IPv6 half of it. -:doc:`pcapkit/foundation/engines/index` tabulates that. +:doc:`/pcapkit/foundation/engines/index` tabulates that. Checksum and Integrity Verification ----------------------------------- diff --git a/docs/source/releasing.rst b/docs/source/contributing/releasing.rst similarity index 100% rename from docs/source/releasing.rst rename to docs/source/contributing/releasing.rst diff --git a/docs/source/testing.rst b/docs/source/contributing/testing.rst similarity index 100% rename from docs/source/testing.rst rename to docs/source/contributing/testing.rst diff --git a/docs/source/workflows.rst b/docs/source/contributing/workflows.rst similarity index 100% rename from docs/source/workflows.rst rename to docs/source/contributing/workflows.rst diff --git a/docs/source/index.rst b/docs/source/index.rst index 490be462b9..877a9f5c99 100644 --- a/docs/source/index.rst +++ b/docs/source/index.rst @@ -29,13 +29,17 @@ construction and analysis library. ext demo - testing - conventions - releasing - workflows - pep changelog +.. toctree:: + :maxdepth: 1 + + contributing/testing + contributing/conventions + contributing/releasing + contributing/workflows + contributing/pep + About ===== diff --git a/docs/source/pcapkit/protocols/internet/mh.rst b/docs/source/pcapkit/protocols/internet/mh.rst index a1bc42583d..d81cbcd581 100644 --- a/docs/source/pcapkit/protocols/internet/mh.rst +++ b/docs/source/pcapkit/protocols/internet/mh.rst @@ -23,7 +23,7 @@ Octets Bits Name Description The CGA Parameters option (type 12) is the one registered mobility option still on the generic handler. It is unreachable rather than unimplemented -- - see the Mobility Header section of :doc:`/pep` for the two faults involved, + see the Mobility Header section of :doc:`/contributing/pep` for the two faults involved, both of which are in shared field machinery rather than here. .. autoclass:: pcapkit.protocols.internet.mh.MH diff --git a/tests/corekit/test_enum_lookup_base_unit.py b/tests/corekit/test_enum_lookup_base_unit.py index cc9a62eb06..2c06f0b746 100644 --- a/tests/corekit/test_enum_lookup_base_unit.py +++ b/tests/corekit/test_enum_lookup_base_unit.py @@ -213,7 +213,7 @@ def test_str_lookup_by_name_and_by_value(self) -> 'None': """Including a value that is not also a member name. ``_Str.get('')`` is the measurement - :file:`docs/source/conventions.rst` records on + :file:`docs/source/contributing/conventions.rst` records on :class:`~pcapkit.const.ftp.command.FEATCode`, made here on a class that cannot be overriding ``get``, since it defines none. diff --git a/tests/corekit/test_fields_numbers_unassigned_enum.py b/tests/corekit/test_fields_numbers_unassigned_enum.py index 8d4450d776..1c2929114e 100644 --- a/tests/corekit/test_fields_numbers_unassigned_enum.py +++ b/tests/corekit/test_fields_numbers_unassigned_enum.py @@ -184,7 +184,7 @@ def test_a_missing_rule_still_takes_precedence_over_the_fallback(self) -> None: ``0x0bad0bad`` is in one of the ``Reserved_*`` ranges :meth:`BlockType._missing_ ` covers. Per the - mint/unmint ruling recorded for #775 (``docs/source/conventions.rst``), + mint/unmint ruling recorded for #775 (``docs/source/contributing/conventions.rst``), ``Reserved`` names a procedure rather than a party, so this range no longer *mints* a registered ``Reserved_0bad0bad`` member -- it now returns an unregistered member via ``_unregistered_member``, bearing the diff --git a/tests/protocols/misc/test_pcapng_unit.py b/tests/protocols/misc/test_pcapng_unit.py index 8847130e69..ac5a47b7e8 100644 --- a/tests/protocols/misc/test_pcapng_unit.py +++ b/tests/protocols/misc/test_pcapng_unit.py @@ -777,7 +777,7 @@ def test_pcapng_option_readers_cover_block_families_and_guards(self) -> None: UnknownOption) from pcapkit.utilities.exceptions import ProtocolError - # Per the mint/unmint ruling for #775 (``docs/source/conventions.rst``), + # Per the mint/unmint ruling for #775 (``docs/source/contributing/conventions.rst``), # ``Unassigned`` names a procedure rather than a party, so ``FilterType``'s # ``_missing_`` no longer mints a registered ``Unassigned_0`` member for # code 0 -- it returns an unregistered member bearing the bare label @@ -1953,7 +1953,7 @@ def test_pcapng_remaining_constructor_branches_and_custom_dispatch(self) -> None UnknownSecrets as SchemaUnknownSecrets) from pcapkit.utilities.exceptions import ProtocolError - # Per the mint/unmint ruling for #775 (``docs/source/conventions.rst``), + # Per the mint/unmint ruling for #775 (``docs/source/contributing/conventions.rst``), # ``Unassigned`` names a procedure rather than a party, so ``FilterType``'s # ``_missing_`` no longer mints a registered ``Unassigned_0`` member for # code 0 -- it returns an unregistered member bearing the bare label