docs: move the process pages out of the docs top level (#901)

.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

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

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 |
 

docs/source/pep.rst → 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 <https://github.com/JarryShaw/PyPCAPKit/issues/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,15 +569,15 @@ 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
 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
 -----------------------------------

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
 =====
 

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

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('<angled>')`` 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.
 

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_
         <pcapkit.const.pcapng.block_type.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

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