Skip to content

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

Description

@allen0099

0.3.8 adds a runnable examples/ directory with a test that exercises each app. The docs still carry their own copies of the same code, so the two can drift apart again.

Proposal

  • Enable pymdownx.snippets in both zensical.toml and zensical.zh-TW.toml, with check_paths = true so a missing file fails the strict build.
  • Replace the full-app examples in the guides with --8<-- includes of the matching examples/*.py (whole file or named sections), in EN and zh-TW.
  • Short fragments that only illustrate one call may stay inline.
  • Keep comments inside the example files in English; the zh-TW pages explain the code around the include.

Done when

  • Every complete app shown in the docs comes from a file under examples/.
  • Both strict docs builds pass, and tests/test_examples.py covers every included file.

Activity

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    documentationImprovements or additions to documentation

    Projects

    No projects

      Milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions