docs: give this project a documentation site, built the way that actually works - #61
Merged
Conversation
…ally works This was the one repository in the family with no docs site at all: no mkdocs.yml, no Pages workflow, nine loose files browsable only on GitHub. The setup is ported from devrepro-doctor, but not as it stood. Porting it is what revealed that devrepro-doctor's own site had been publishing empty pages for months: every `--8<--` include there used a `../` path, which pymdownx.snippets refuses because it escapes base_path, and `check_paths: false` made the refusal silent. I wrote the same broken pattern here first, hit the same failure, and went back to check whether it had ever worked there. It had not. So this site uses base_path at the repository root with includes that stay inside it, and `check_paths: true` so a missing snippet fails the build rather than quietly producing a page of navigation chrome. Root documents stay the single source of truth; the site includes them rather than copying them. scripts/check_docs_site.py asserts the built site has content. Its threshold is split by page kind, which the first version got wrong: a flat 120-word bar reported docs/sdk.md (18 lines, mostly a code block) and docs/spec-support.md as broken when both are simply terse. The defect being guarded is an include resolving to nothing, so include-backed pages get the strict bar and everything else only has to be non-blank. Worth recording: my own scripts/check_action_pins.py caught two invented SHAs in this workflow. I had typed the Pages action pins from memory instead of copying them, and neither resolved to any tag. That is exactly the check it was written for, catching exactly the mistake it was written for, on its author. 20 pages build, all carrying real content, and the README links the site.
|
You have reached your Codex usage limits for code reviews. You can see your limits in the Codex usage dashboard. |
API Verity — contract reviewOne comment per PR — updated on each push. |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
This was the one repository in the family with no docs site at all — no
mkdocs.yml, no Pages workflow, nine loose files browsable only on GitHub.Porting it found a live bug in the source it was ported from
The setup comes from
devrepro-doctor, but not as it stood. I wrote the same include pattern here first, hit a failure, and went back to ask whether it had ever worked there.It hadn't. Every
--8<--include in that project used a../path — whichpymdownx.snippetsrefuses because it escapesbase_path— andcheck_paths: falsemade the refusal silent. Its published site had been serving Architecture, Roadmap, Contributing and five other pages as 68 words of navigation chrome. Fixed separately in devrepro-doctor#35.So this site is built the way that works
base_pathat the repository root, with includes that stay inside it.check_paths: true— a missing snippet fails the build rather than quietly producing an empty page.The content check, and what I got wrong in it
scripts/check_docs_site.pyasserts the built site has content. My first version used a flat 120-word threshold and reporteddocs/sdk.md(18 lines, mostly a code block) anddocs/spec-support.mdas broken — both are simply terse.The threshold is now split by page kind, because the defect being guarded is an include resolving to nothing: include-backed pages get the strict bar, everything else only has to be non-blank. Tuning a global number would have papered over the distinction.
The pin checker caught me
scripts/check_action_pins.py— added earlier in this run — rejected two invented SHAs in this very workflow. I had typed the Pages action pins from memory instead of copying them, and neither resolved to any tag.That is the check doing exactly what it was written for, to exactly the mistake it was written for, on its author.
Verification
ruff/ruff format --checkmypypytestmkdocs build --strictcheck_docs_site.pycheck_action_pins.py