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

Is your feature request related to a problem? Please describe.

docs/source/ has grown to eight top-level .rst pages against only two content subdirectories. The maintainer's ask, verbatim, on #719:

testing/conventions/releasing.rst and other similar docs might go to another subdirectory to keep the toplevel docs clean.

Current top level:

changelog.rst   conventions.rst   demo.rst   ext.rst
index.rst       pep.rst           releasing.rst   testing.rst

Subdirectories: changelog/, pcapkit/ (plus _static/, _templates/).

Describe the solution you'd like

Move the maintainer-facing / process pages into a subdirectory, leaving the top level to index.rst and whatever genuinely belongs beside it. conventions.rst, releasing.rst and testing.rst are named explicitly; decide per page for demo.rst, ext.rst, pep.rst and changelog.rst and say why in the PR.

Do it in one change covering every page that moves. Moving them piecemeal produces exactly the inconsistency this issue exists to remove.

What a move has to keep working

every toctree entry in docs/source/index.rst;
every :doc: cross-reference between these pages — releasing.rst and the new workflows.rst reference each other;
any :file: or relative path inside the moved pages;
the Sphinx build with no new warnings — there are 42 pre-existing ones, so measure the delta rather than the total.

Additional context

docs/source/workflows.rst is added by #898 as a ninth top-level page. That was a deliberate call rather than an oversight: it lands at the top level and moves here with the rest. Its reviewer was told the placement is not a defect.

Note that in a worktree the venv's editable install wins over cwd when building docs, so export PYTHONPATH=<worktree> and confirm the doc root Sphinx reports before trusting a build result.

Split out of #719, which is the prose sweep; this is structural.

Checkable blocker, recorded so this label is not taken on trust: PR #898.

#898 adds docs/source/workflows.rst as a ninth top-level page and is currently at review: needs-changes with five defects being fixed. Moving the top-level pages while a new one is mid-flight would either conflict with that branch or land it in the old location and need a second move.

Two commands settle whether this is still blocked at any moment:

gh pr view 898 -R JarryShaw/PyPCAPKit --json state,labels -q '"\(.state) \([.labels[].name]|join(","))"'
ls docs/source/*.rst

Unblocks when #898 merges. At that point the move covers nine pages — changelog, conventions, demo, ext, pep, releasing, testing, workflows, and a decision on index — in one change.

The blocker I recorded is discharged — #898 merged as f35e02ec4 at 04:47:57Z — but it is replaced rather than lifted, and I am not dispatching into a conflict.

New checkable blocker: four open PRs still edit the very top-level pages this issue moves. Measured just now:

#905  docs/source/releasing.rst     review: good-to-go, awaiting merge
#906  docs/source/conventions.rst   review: good-to-go, awaiting merge
#907  docs/source/conventions.rst   review: good-to-go, awaiting merge
#909  docs/source/changelog.rst     review: good-to-go, awaiting merge

Moving a file that four in-flight branches are editing produces a conflict in every one of them, and the conflict lands on their side — they would each need a rebase across a path change, which is far more expensive than this issue waiting. workflows.rst is now safe (its PR merged), which is genuine progress: the move set is settled at nine pages and one of them is no longer contested.

One command settles whether this is still blocked at any moment:

for n in 905 906 907 909; do gh api "repos/JarryShaw/PyPCAPKit/pulls/$n/files" --paginate \
  -q '.[].filename' | grep -E '^docs/source/[^/]+\.rst$'; done

Empty output, or all four merged, means go.

Why this is worth stating rather than just re-labelling. The original blocker was "a ninth page is mid-flight". That reasoning was too narrow — it happened to be true of workflows.rst but the real constraint is any open branch editing any page in the move set. Recording the narrow version is how a blocker gets discharged on a technicality while the actual obstacle stands. The check above is the general form.

Sequencing note for whoever picks this up: #902 is blocked on this issue, and its :file:-reference audit genuinely has to run after the move, since a moved page changes what a relative path resolves to. So the chain is: those four merge → #901 moves the pages → #902 audits the references. Doing #902 first means auditing paths that are about to change.

Unblocked — every PR that was editing a page in the move set has merged. The general check I recorded now returns empty:

for n in <every open PR>; do gh api .../files | grep -E '^docs/source/[^/]+\.rst$'; done
  -> (no output)

The four that held it: #905 539a3c54d (releasing.rst), #906 c50f442db (conventions.rst), #907 ef4ba1afd (conventions.rst), #909 e38d695ae (changelog.rst) — plus #898 f35e02ec4 (workflows.rst) earlier. Only #904 and #657 remain open, and neither touches a top-level docs page.

So the move set is settled at nine pages and none is contested:

changelog.rst  conventions.rst  demo.rst  ext.rst  index.rst
pep.rst        releasing.rst    testing.rst        workflows.rst

blocked removed, wip applied, worker dispatched.

Worth noting how this unblocked, because the first version of the blocker would have missed it. I originally recorded this as blocked on "#898, a ninth top-level page mid-flight". #898 merged at 04:47 and by that wording it unblocked — but four other branches were still editing pages in the set, so moving then would have pushed a conflict onto each of them. Rewriting the blocker in its general form (any open branch editing any page in the set) is what kept it honest for the next twenty minutes, and it is the form the check above tests.

Reminder carried forward: #902 is blocked on this, and genuinely so — its :file:-reference audit has to run after the move, since a moved page changes what a relative path resolves to. Auditing first means auditing paths that are about to change.

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

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

Navigation Menu

Repository navigation

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

Metadata

Assignees

Labels

Projects

Milestone

Relationships

Development

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

Description

Activity

JarryShaw commented on Sep 29, 2026

JarryShaw commented on Sep 29, 2026

JarryShaw commented on Sep 29, 2026

Metadata

Metadata

Assignees

Labels

Projects

Milestone

Relationships

Development

Issue actions