question-mark
Stuck on an issue?

Lightrun Answers was designed to reduce the constant googling that comes with debugging 3rd party libraries. It collects links to all the places you might be looking at while hunting down a tough bug.

And, if you’re still stuck at the end, we’re happy to hop on a call to see how we can help out.

Add tests to verify the documentation examples are valid

See original GitHub issue

At the moment one of the examples in the docs doesn’t compile

https://github.com/krzema12/github-actions-kotlin-dsl/blob/32576f647c533f087eed07a93564a56f418d78cd/docs/user-guide/getting_started.md?plain=1#L35-L45

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:open
  • Created a year ago
  • Reactions:2
  • Comments:6 (5 by maintainers)

github_iconTop GitHub Comments

1reaction
jmfayardcommented, Jul 2, 2022

@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>

1reaction
aSemycommented, Apr 23, 2022

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

Read more comments on GitHub >

github_iconTop 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 >

github_iconTop Related Medium Post

No results found

github_iconTop Related StackOverflow Question

No results found

github_iconTroubleshoot Live Code

Lightrun enables developers to add logs, metrics and snapshots to live code - no restarts or redeploys required.
Start Free

github_iconTop Related Reddit Thread

No results found

github_iconTop Related Hackernoon Post

No results found

github_iconTop Related Tweet

No results found

github_iconTop Related Dev.to Post

No results found

github_iconTop Related Hashnode Post

No results found