docs: ruff-format & compile-check examples; Tonnikala syntax; package guidance - #8
Merged
Conversation
Adds tools/format_doc_examples.py, a self-contained uv script that extracts the Python code-block examples from the reStructuredText docs and runs them through ruff format (pinned ruff==0.4.4, matching the ruff-format pre-commit hook), so documentation snippets follow the same style as the rest of the source tree. Supports --check for CI and skips intentionally partial snippets. Wires it into .pre-commit-config.yaml as a local hook that checks docs/**.rst, and reformats all 113 drifting examples across the narrative and tutorial docs. Claude-Session: https://claude.ai/code/session_011KKd5BtHMWfrF9WRRMwg7F
- Templates: use Tonnikala syntax throughout instead of Chameleon. Replace the Chameleon ``|n`` no-escape filter with Tonnikala's $literal(...), rename ``.pt``/``.html`` renderer targets to ``.tk``, drop the "Chameleon template" labels, and use bare $ interpolation for attribute/call chains (csrf token, static_url) to match templating.rst. - Tutorials: replace datetime.utcnow with timezone-aware datetime.now(timezone.utc) (and add the missing datetime import in the JSON error-adapter example). - Quickstart: note that a single file is fine for small apps but real applications should be organised as a package, with a recommended layout. Claude-Session: https://claude.ai/code/session_011KKd5BtHMWfrF9WRRMwg7F
Adds tools/doc_examples.py, a stdlib RST code-block extractor shared by the formatter and a new tests/test_doc_examples.py that compile()s all 196 Python examples (guarding against syntactically broken or tooling-mangled snippets). Refactors format_doc_examples.py to reuse the shared parser, and adds a compile-doc-examples pre-commit hook alongside the pytest gate. Snippets can opt out with a '.. doc-example: no-compile' comment. Claude-Session: https://claude.ai/code/session_011KKd5BtHMWfrF9WRRMwg7F
Member
Author
|
Bypassing review as it is essentially documentation formatting. |
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.
Documentation correctness & tooling
Three related fixes to the narrative/tutorial docs, plus tooling to keep them honest.
1. ruff-format every example (
f9e703e)All 196
code-block:: pythonexamples are now formatted exactly like the source tree. Addstools/format_doc_examples.py— a self-containeduvscript that extracts each example, runs it throughruff format(pinnedruff==0.4.4, matching theruff-formatpre-commit hook), and reindents it back into the RST. Supports--check; wired in as a pre-commit hook overdocs/**.rst. 113 examples reformatted.2. Correct template syntax, datetimes, project layout (
8eb4452)|nno-escape filter with Tonnikala's$literal(...), renamed.pt/.htmlrenderer targets to.tk, dropped the "Chameleon template" labels, and switched attribute/call chains (CSRF token,static_url) to bare$interpolation to matchtemplating.rst.datetime.utcnowwithdatetime.now(timezone.utc)across the tutorials (and added a missingdatetimeimport the JSON error-adapter example needed).3. Compile-check every example (
05137fe)Adds
tools/doc_examples.py(stdlib RST extractor, shared with the formatter) andtests/test_doc_examples.py, whichcompile()s all 196 examples so syntactically broken or tooling-mangled snippets fail CI. Also acompile-doc-examplespre-commit hook. Snippets can opt out with.. doc-example: no-compile.Verification
rstcheckclean acrossdocs/tests/test_doc_examples.py: 197 passedruff check/ruff format --checkclean (pinned 0.4.4)https://claude.ai/code/session_011KKd5BtHMWfrF9WRRMwg7F