Skip to content

docs: include the examples/ files instead of copying code into the guides - #357

Merged
allen0099 merged 1 commit into
masterfrom
docs/289-include-examples
Sep 29, 2026
Merged

allen0099 merged 1 commit into
masterfrom
docs/289-include-examples

Conversation

@allen0099

Copy link
Copy Markdown
Owner

Closes #289

The guides now pull full-app code from examples/*.py with pymdownx.snippets (already enabled with check_paths = true in both Zensical configs), so the code on the page is the code tests/test_examples.py runs. A missing file or section fails the strict build.

Converted (EN and zh-TW)

  • HTTP_CACHING: intro app → examples/http_cache.py:routes; protected monitoring routes → examples/http_cache.py:admin.
  • BACKENDS: "Closing a backend" → examples/redis_backend.py:lifespan.
  • STATE: quick start → whole examples/oauth_state.py.
  • SESSION: Basic Usage → new examples/session_api.py; Full Example (Redis) → new examples/session_redis.py.
  • JWT_CLAIMS: base serializer, multi-tenant serializer, Option 1 setup and the complete application → sections of new examples/session_jwt_claims.py.

The new examples have tests in tests/test_examples.py. The JWT one is skipped without the jwt extra, and the Redis one uses the same live-server opt-in as the existing Redis example. It uses its own key prefix, and clear() only touches that namespace. Section markers are # --8<-- [start:name] / # --8<-- [end:name], documented in examples/README.md, and they do not show up in the rendered page.

Left inline

  • README / zh-TW index quick start: the README is also rendered on PyPI and GitHub, where snippets do not run.
  • Short fragments (one call or a parameter reference): add_routes parameters, APP_CACHE and LOCK API fragments, the atomic-primitives fragment, HTTP_CACHING fragments that build on an app defined elsewhere, JWT_CLAIMS Example 1 / Option 2 / key rotation / testing snippets, CACHE_FLOW, and the SessionManagerProxy alternative in SESSION.

Other changes

  • Include fences are wrapped in <!-- fmt:off --> / <!-- fmt:on -->. Without the wrapper, ruff-format rewrites --8<-- "..." in markdown code blocks as a Python expression.
  • docs.yml also runs on examples/** changes.
  • DEVELOPMENT.md explains how to include an example. The zh-TW GLOSSARY notes that included code keeps English comments.

Checks

  • zensical build --strict passes 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.

…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.
@allen0099
allen0099 merged commit 3ac72b9 into master Sep 29, 2026
12 checks passed
@allen0099
allen0099 deleted the docs/289-include-examples branch September 29, 2026 08:15
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.

Docs: include the examples/ files instead of copying code into the guides

1 participant