Skip to content

feat(docs): pilot README and documentation quality checks - #37

Merged
NaNIsaac merged 2 commits into
mainfrom
feat/docs-quality-pilot
Nov 1, 2026
Merged

NaNIsaac merged 2 commits into
mainfrom
feat/docs-quality-pilot

Conversation

@NaNIsaac

@NaNIsaac NaNIsaac commented Oct 31, 2026 •

Copy link
Copy Markdown
Owner

README structure and navigation checks now enforce the documentation pilot in QoraGeom and QoraPhase, while other repositories receive non-failing warnings. Reasoned exemptions use the existing .conventions.toml mechanism. CONVENTIONS defines the 200-line first screen and the documentation layout.

The shared README workflow also runs marked Markdown blocks recursively under docs/ on Ubuntu. Existing README platform coverage stays unchanged. The local CI runner executes documentation examples on Linux and explicitly reports them as not run on other hosts. Malformed marked fences fail immediately instead of hanging. Blocks stop at the first failed shell or native PowerShell command; the runner requires PowerShell 7.3 or later.

Fixes #36.
Fixes #38.

Rubric Result
Matches the code New checks and rollout match the documented policy; fixtures cover heading order, missing headings, 200/201-line boundary, nested navigation, invalid JSON and exemptions.
First execution succeeds Local CI passed on Windows: both existing selftests, three documentation unit tests, isolated PowerShell runner regression tests and Ruff.
Example output matches actual execution Runner fixture writes the expected result; dry-run produces no file; failed examples, intermediate native/shell failures and malformed fences are rejected. No consumer example output is changed here.
Physics or equations need review No scientific claims, formulas or numerical code changed.
README lines before / after 5 / 5; this PR establishes tooling, with consumer documentation changes following separately.

Validation:

uv run tools/local_ci.py .
local-ci: 0c4d91dd207a48355a89e8e8d9aa50bad4f5cf0b | ruff ok | pytest n/a | readme n/a | selftest ok | uv ok

The full local record reports the unrun second matrix combination and that Ubuntu jobs ran on a Windows host. Ubuntu workflow execution and hosted Actions were not tested locally. The reusable workflow is consumed from main, so downstream CI receives these checks after this change is integrated. No consumer repository, release or installed tool was changed.

@NaNIsaac
NaNIsaac merged commit dcc94a6 into main Nov 1, 2026
3 checks passed
@NaNIsaac
NaNIsaac deleted the feat/docs-quality-pilot branch November 1, 2026 07:24
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Marked documentation blocks hide intermediate command failures README runner hangs when a marked code fence is missing

1 participant