Context
The feat/doc-example-testing branch (now merged) added a mechanism for
testing code snippets in the docs: snippets are kept as separate files,
pulled into the .md pages via an include module, tested, and
the final docs are built with mkdocs build.
The system works, but there is no written guide on how to use it. A
developer who wants to add a new documentation page with a tested code
example currently has to reverse-engineer the workflow. We need a short
guide covering:
- where to put the code snippet file
- how to include it in the .md page
- how the snippet is picked up by the test
- how to build and verify the page with mkdocs
Open question: where should this guide live (a docs page, the README, or a
CONTRIBUTING file)? Not decided yet, but we shouldn't lose this knowledge.
Alternatives
We could leave the code-snippets out and letting them only live in the
*.md files. But then we would risk that those snippets don´t work.
Has the feature been requested before?
Not that I'm aware of.
If the feature request is approved, would you be willing to submit a PR?
Yes
Context
The feat/doc-example-testing branch (now merged) added a mechanism for
testing code snippets in the docs: snippets are kept as separate files,
pulled into the .md pages via an include module, tested, and
the final docs are built with
mkdocs build.The system works, but there is no written guide on how to use it. A
developer who wants to add a new documentation page with a tested code
example currently has to reverse-engineer the workflow. We need a short
guide covering:
Open question: where should this guide live (a docs page, the README, or a
CONTRIBUTING file)? Not decided yet, but we shouldn't lose this knowledge.
Alternatives
We could leave the code-snippets out and letting them only live in the
*.md files. But then we would risk that those snippets don´t work.
Has the feature been requested before?
Not that I'm aware of.
If the feature request is approved, would you be willing to submit a PR?
Yes