Re:Technical documentation that just works
by kxc42 on Thursday May 27, 2021 @06:20PM
(#27309293)
Basically you have three approaches to tackle code samples in markdown files:
1. run the code with some kind of plugin as part of your doc pipeline
2. generate documentation from your code
3. take some kind of hybrid approach
I went for 3., annotate snippet "areas" in the source code of a project (mainly in tests) and extract the snippets to a folder, e.g. into the mkdocs folder. I commit them to the (docs) repo. If the project changes, usually I fix the tests and update the snippets in mkdocs. This way I can be sure that the code in the documentation is actually working and people can copy&paste it. To scratch my own itch, I (surprise, surprise) created a script and even packaged it[1].
1. run the code with some kind of plugin as part of your doc pipeline
2. generate documentation from your code
3. take some kind of hybrid approach
I went for 3., annotate snippet "areas" in the source code of a project (mainly in tests) and extract the snippets to a folder, e.g. into the mkdocs folder. I commit them to the (docs) repo. If the project changes, usually I fix the tests and update the snippets in mkdocs. This way I can be sure that the code in the documentation is actually working and people can copy&paste it. To scratch my own itch, I (surprise, surprise) created a script and even packaged it[1].
[1]: https://pypi.org/project/snex/