[thangalin]

> difficult to keep [...] docs updated with actual code

I used my software and R Markdown documents to help address such problems. In the source code, you have:

    // DOC SNIPPET BEGAN: example_api_usage
    /**
     */
    function amazing_function( char life, long universe, string everything ) {
    } 
    // DOC SNIPPET ENDED

In the R Markdown you write an R function to parse all snippets, then refer to snippets by name. If the snippet can't be found, building the documentation fails, and noisily breaks a CI/CD pipeline.

What's nice is that you can then use this to parse C++ definitions into Markdown tables to render nicely formatted content.

The general idea is that you can have "living" documentation reference source code and break on mismatch. Whether you use knitr/pandoc or python or KeenWrite/R Markdown[1] is an implementation detail.

[1]: https://keenwrite.com/

[moritz]

In the Elixir ecosystem (where documentation is considered a "first-class citizen" in the language), you can run code examples as part of your test suite in a similar fashion ("doctest"): https://elixir-recipes.github.io/testing/doctests/

[thangalin]

> documentation is considered a "first-class citizen"

How exquisitely Knuthian!