Skip to content

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

Merged
JarryShaw merged 1 commit into
mainfrom
refactor/901-docs-move-process-pages
Sep 29, 2026
Merged

JarryShaw merged 1 commit into
mainfrom
refactor/901-docs-move-process-pages

Conversation

@JarryShaw

@JarryShaw JarryShaw commented Sep 29, 2026 •

Copy link
Copy Markdown
Owner
  • Searched for similar pull requests
  • Followed the coding style (make pylint, make mypy, make isort)
  • make test passes, and a test case covers the change
  • Added a changelog entry under docs/source/changelog/ and regenerated CHANGELOG.md, if the change is user-visible

What is the purpose of your pull request?

  • fix
  • feat
  • perf
  • refactor
  • test
  • docs
  • ci
  • chore

Description of your pull request and other information

Closes #901. Moves conventions.rst, releasing.rst, testing.rst, workflows.rst and pep.rst into a new docs/source/contributing/ subdirectory via git mv, one commit. demo.rst, ext.rst and changelog.rst stay at the top level (library-usage docs, not process); index.rst is the root document.

Fixed every reference the move touched: index.rst's toctree, the one cross-tree :doc: link that broke (pcapkit/protocols/internet/mh.rst → /pep), pep.rst's own eleven :doc: links, which gained a leading / -- ten into pcapkit/, plus one to /ext, a page that stays at the root, and the plain-text path mentions in CONTRIBUTING.md, README.md, a workflow comment, and four test docstrings/comments.

Splitting the toctree moves changelog from last to third in the rendered nav.

Sphinx build: 58 warnings, same as the 58-warning baseline (delta 0). util/changelog_md.py --check exits 0 (unaffected -- 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. make isort clean; make pylint/make mypy carry their pre-existing, advisory findings, none in a file this PR touches (no pcapkit/*.py changed). Ran tests/project/ (178 tests) plus the touched unit tests rather than the full suite, which OOMs locally.

Changelog: N/A -- changelog centralised in #657.

@JarryShaw JarryShaw added docs Pull requests that change documentation only (docs: subject prefix) refactor Restructuring for its own sake — neither a fix nor a new capability (refactor: prefix) review: pending No verdict for the current head - never reviewed, or the head moved since the last one labels Sep 29, 2026
* `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.
@JarryShaw
JarryShaw force-pushed the refactor/901-docs-move-process-pages branch from c38640a to c239631 Compare September 29, 2026 05:53
@JarryShaw JarryShaw added review: good-to-go Cross-review at the current head says ready; CI state is separate and removed review: pending No verdict for the current head - never reviewed, or the head moved since the last one labels Sep 29, 2026
@JarryShaw

Copy link
Copy Markdown
Owner Author

Good to merge — cross-review on a different model (sonnet; authored by opus) came back needs changes, prose only, and I have made exactly those fixes. The tree is byte-identical to the reviewed one (git diff c38640aa4 c23963171 is empty); only the commit message and PR body changed.

What it verified: four of the five moves are R100 byte-identical blobs, pep.rst is R098 for its reference edits alone, and a repo-wide sweep for :doc:/:file:/:ref:/bare-path/toctree/rendered-.html forms found zero broken or misdirected references. Sphinx warning delta 0 (58 → 58, from Sphinx's own summary lines, with the two warning sets identical line-for-line after normalising the tree prefix). The six relative sibling refs in releasing.rst and workflows.rst resolve in the built HTML, which is the mechanical reason pep.rst and workflows.rst had to move with the owner's three rather than a matter of taste.

What it disputed, all three confirmed by me directly and now corrected:

  • The message claimed pep.rst's refs to ext/releasing/workflows "needed no change, since those move together". ext.rst does not move, its reference did change (:doc:`ext``` → :doc:/ext```), and releasing/workflowsare not referenced frompep.rstat all — 0 hits. Eleven refs changed, not ten, and six of the eleven are outsideconst/`.
  • "Nothing shipped changed" proved only that the sdist file list is unchanged (928 entries, identical tar tzf). Six shipped files change content, because MANIFEST.in's prune test is singular and does not match tests/. Comment/docstring/URL text only.
  • The toctree split moves changelog from last to third in the nav; now stated.

Unverified and stated as such: the author's intermediate 59-warning build was not reproduced, and make pylint/mypy were not re-run (no pcapkit/*.py changed).

@JarryShaw
JarryShaw merged commit 9806f16 into main Sep 29, 2026
63 checks passed
@JarryShaw
JarryShaw deleted the refactor/901-docs-move-process-pages branch September 29, 2026 13:03
@JarryShaw JarryShaw removed the review: good-to-go Cross-review at the current head says ready; CI state is separate label Sep 29, 2026
JarryShaw added a commit that referenced this pull request Sep 29, 2026
…912 tense (#920)

- `_sentinel_section()` walked a two-element candidate tuple whose first
  entry, `docs/source/conventions.rst`, has not existed since #912 moved
  the file in `9806f16aa`. The loop always fell through to the second, so
  it was dead code that read as though both locations were still live.
  Resolved to the real path directly instead.
- Its docstring described the move as something #912 "is making". #912
  has merged; the tense now says so.

Comment-only and docstring-only; no assertion changed. Verified:
`tests/corekit/test_sentinel_exports_unit.py` 18 tests OK,
`tests/project/test_isort_clean.py` OK, and no occurrence of the pre-move
path survives anywhere under `pcapkit/`, `tests/` or `docs/`.
@JarryShaw JarryShaw added this to the 1.5 milestone Oct 6, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

docs Pull requests that change documentation only (docs: subject prefix) refactor Restructuring for its own sake — neither a fix nor a new capability (refactor: prefix)

Projects

Status: Done

Development

Successfully merging this pull request may close these issues.

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

1 participant