Repository navigation
refactor(docs): move the process pages out of the docs top level #901
Description
Activity
- changed the title
[-]refactor(docs)[/-][+]refactor(docs): move the process pages out of the docs top level[/+]on Sep 29, 2026 Checkable blocker, recorded so this label is not taken on trust: PR #898.
#898 adds
docs/source/workflows.rstas a ninth top-level page and is currently atreview: needs-changeswith 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 onindex— in one change.The blocker I recorded is discharged — #898 merged as
f35e02ec4at 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 mergeMoving 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.rstis 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.rstbut 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), #906c50f442db(conventions.rst), #907ef4ba1afd(conventions.rst), #909e38d695ae(changelog.rst) — plus #898f35e02ec4(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.rstblockedremoved,wipapplied, 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.
Is your feature request related to a problem? Please describe.
docs/source/has grown to eight top-level.rstpages against only two content subdirectories. The maintainer's ask, verbatim, on #719:Current top level:
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.rstand whatever genuinely belongs beside it.conventions.rst,releasing.rstandtesting.rstare named explicitly; decide per page fordemo.rst,ext.rst,pep.rstandchangelog.rstand 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
toctreeentry indocs/source/index.rst;:doc:cross-reference between these pages —releasing.rstand the newworkflows.rstreference each other;:file:or relative path inside the moved pages;Additional context
docs/source/workflows.rstis 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.