> 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/
I used my software and R Markdown documents to help address such problems. In the source code, you have:
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/