3 ms·

I wish all API doc generators test the doc code examples like this https://rust-lang.github.io/mdBook/cli/test.html https://rust-lang.github.io/mdBook/cli/test.

by Jakob 2y ago

I wish all API doc generators test the doc code examples like this https://rust-lang.github.io/mdBook/cli/test.html https://rust-lang.github.io/mdBook/cli/test.html Even if the code example works today, it might not in the future and tests prevent people getting stuck on outdated docs like we often see.

jillesvangurp 2y ago
I actually wrote a kotlin library (https://github.com/jillesvangurp/kotlin4example https://github.com/jillesvangurp/kotlin4example) a while ago to help me write documentation that is generated from code that actually compiles and runs. Instead of embedding code in markdown, I actually generate the markdown from code. Which with Kotlin is easy because you can write your own DSLs. And I get to refactor my code and documentation at the same time. It has some other nifty features like capturing output that you can show in the Markdown and a few other things. If you want to see it in action, check out the documentation for my kt-search project. There are probably a lot of other libraries out there that do similar things. But it's a thing that most projects don't seem to rely on for their documentation. And breaking code samples are a major hurdle for writing documentation to begin with. I find that addressing that gets you in a mode where you are documenting things by default. And good documentation also reveals design flaws because you are kind of forced to eat your own dog food by writing working code that shows how you would use a particular feature. I'm basically constantly trying to make life easier for both myself and my users.
- mkesper 2y ago
  Reminds me of Knuth's literate programming: https://www-cs-faculty.stanford.edu/~knuth/lp.html https://www-cs-faculty.stanford.edu/~knuth/lp.html
  - jillesvangurp 2y ago
    That was a direct inspiration.
boxed 2y ago
I wrote a ton of custom code to do this for iommi (example: https://docs.iommi.rocks/en/latest/tutorial.html https://docs.iommi.rocks/en/latest/tutorial.html). I went further than any other library I've seen and made it so that the views in the examples produce static html files that are embedded in the resulting output via iframes.

by Jakob 2y ago

jillesvangurp 2y ago

I actually wrote a kotlin library (https://github.com/jillesvangurp/kotlin4example https://github.com/jillesvangurp/kotlin4example) a while ago to help me write documentation that is generated from code that actually compiles and runs. Instead of embedding code in markdown, I actually generate the markdown from code. Which with Kotlin is easy because you can write your own DSLs. And I get to refactor my code and documentation at the same time. It has some other nifty features like capturing output that you can show in the Markdown and a few other things. If you want to see it in action, check out the documentation for my kt-search project. There are probably a lot of other libraries out there that do similar things. But it's a thing that most projects don't seem to rely on for their documentation. And breaking code samples are a major hurdle for writing documentation to begin with. I find that addressing that gets you in a mode where you are documenting things by default. And good documentation also reveals design flaws because you are kind of forced to eat your own dog food by writing working code that shows how you would use a particular feature. I'm basically constantly trying to make life easier for both myself and my users.

mkesper 2y ago
Reminds me of Knuth's literate programming: https://www-cs-faculty.stanford.edu/~knuth/lp.html https://www-cs-faculty.stanford.edu/~knuth/lp.html
- jillesvangurp 2y ago
  That was a direct inspiration.

boxed 2y ago

I wrote a ton of custom code to do this for iommi (example: https://docs.iommi.rocks/en/latest/tutorial.html https://docs.iommi.rocks/en/latest/tutorial.html). I went further than any other library I've seen and made it so that the views in the examples produce static html files that are embedded in the resulting output via iframes.