docs: include the examples/ files instead of copying code into the guides - #357
Merged
Merged
Conversation
…ides The guides now pull full-app code from examples/*.py with pymdownx.snippets (whole files or named sections), so the code shown is the code tests/test_examples.py runs. New examples cover the session basic and Redis apps and the JWT custom-claims guide. The docs workflow also runs on examples/ changes.
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
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.
Closes #289
The guides now pull full-app code from
examples/*.pywithpymdownx.snippets(already enabled withcheck_paths = truein both Zensical configs), so the code on the page is the codetests/test_examples.pyruns. A missing file or section fails the strict build.Converted (EN and zh-TW)
examples/http_cache.py:routes; protected monitoring routes →examples/http_cache.py:admin.examples/redis_backend.py:lifespan.examples/oauth_state.py.examples/session_api.py; Full Example (Redis) → newexamples/session_redis.py.examples/session_jwt_claims.py.The new examples have tests in
tests/test_examples.py. The JWT one is skipped without thejwtextra, and the Redis one uses the same live-server opt-in as the existing Redis example. It uses its own key prefix, andclear()only touches that namespace. Section markers are# --8<-- [start:name]/# --8<-- [end:name], documented inexamples/README.md, and they do not show up in the rendered page.Left inline
add_routesparameters, APP_CACHE and LOCK API fragments, the atomic-primitives fragment, HTTP_CACHING fragments that build on anappdefined elsewhere, JWT_CLAIMS Example 1 / Option 2 / key rotation / testing snippets, CACHE_FLOW, and theSessionManagerProxyalternative in SESSION.Other changes
<!-- fmt:off -->/<!-- fmt:on -->. Without the wrapper, ruff-format rewrites--8<-- "..."in markdown code blocks as a Python expression.docs.ymlalso runs onexamples/**changes.Checks
zensical build --strictpasses for EN and zh-TW. The rendered HTML contains the included code and no literal--8<--include lines (the one deliberate escaped example in DEVELOPMENT is the only one).pytest: 1417 passed, including the Redis example. Coverage is 99.91%.pre-commit run --all-files: clean.