Add tests to verify the documentation examples are valid
See original GitHub issueAt the moment one of the examples in the docs doesn’t compile
job(name = "test_job", runsOn = UbuntuLatest) {
// Error: No value passed for parameter 'id'
I’d like to use Knit to solve the problem of the docs getting out of sync.
Recently I’ve been using Knit to verify that the documentation examples are correct. It provides a simple way of testing any source code that’s in the docs. The tests are then run as part of the usual test suite. If the API changes, then the tests in the docs fail.
A good example project that uses Knit is Kotlinx Serialization: https://github.com/Kotlin/kotlinx.serialization/blob/master/docs/basic-serialization.md#json-encoding
I’ll make a quite demo PR (I’ll base it off the ‘update Gradle’ PR, but it’s not necessary - either can be done independently )
Issue Analytics
- State:
- Created a year ago
- Reactions:2
- Comments:6 (5 by maintainers)
Top Results From Across the Web
Documentation unit tests - Medium
Obviously the tests can't confirm the quality of the documentation, so they are easy to cheat: but they do at least protect against...
Read more >How to Write Test Cases: The Ultimate Guide with Examples
So, it is always better to add a timestamp with the tester's name in the testing comments so that a test result (pass...
Read more >doctest — Test interactive Python examples — Python 3.11.1 ...
To perform regression testing by verifying that interactive examples from a test file or a test object work as expected. To write tutorial...
Read more >Python's doctest: Document and Test Your Code at Once
In this tutorial, you'll learn how to add usage examples to your code's documentation and docstrings and how to use these examples to...
Read more >Documentation tests - The rustdoc book
rustdoc supports executing your documentation examples as tests. This makes sure that examples within your documentation are up to date and working. The...
Read more >Top Related Medium Post
No results found
Top Related StackOverflow Question
No results found
Troubleshoot Live Code
Lightrun enables developers to add logs, metrics and snapshots to live code - no restarts or redeploys required.
Start FreeTop Related Reddit Thread
No results found
Top Related Hackernoon Post
No results found
Top Related Tweet
No results found
Top Related Dev.to Post
No results found
Top Related Hashnode Post
No results found
Top GitHub Comments
@krzema12 mkdocs has a list of plugins here https://github.com/mkdocs/mkdocs/wiki/MkDocs-Plugins
https://github.com/rnorth/mkdocs-codeinclude-plugin seems to be what you are looking for
<rant>
It’s one of the things that everyone needs but is not in markdown. Like for table of contents. So everyone is reinventing the wheel in an incompatible way. Asciidoc does this by default https://docs.asciidoctor.org/asciidoc/latest/directives/include-tagged-regions/</rant>
I’ve found the issue with running the scripts, it’s something to do with kotlinx-knit https://github.com/Kotlin/kotlinx-knit/issues/41