4 ms·
The ability to execute sample code during documentation generation seems invaluable. Instead of being subject to rot, documentation turns into an executable tes
by mfwgenerics 3y ago
The ability to execute sample code during documentation generation seems invaluable. Instead of being subject to rot, documentation turns into an executable test suite.
I've been working on something like this for Kotlin using a compiler plugin that allows code to access the source text of lambdas, functions and classes being executed. You write code that spits out markdown and captures its own source into code blocks.
https://github.com/mfwgenerics/kapshot https://github.com/mfwgenerics/kapshot
- martypitt 3y agoThat's fantastic. We use Kotlin to build Taxi (taxilang.org) and orbitalhq.com. this would be an awesome addition to our docs. However, do I understand it correctly that this allows me to output verified, working code in my test suite, but its not a tool that I can embed in my docs to create runnable code samples? (which is what the OP is showing). super valuable either way, just trying to validate understanding.
- mfwgenerics 3y agoThat sounds about right. The approach I'm working on won't allow you to embed runnable code in your docs. Instead, it requires you to write your documentation in Kotlin e.g. using a Markdown DSL where source code from the codebase can be included in the output. I'm working on a separate project to programmatically generate file trees and Docusaurus doc sites in code. I'm not aware of anything exactly like Livebook in the Kotlin ecosystem but you might be interested in kotlinx-knit which takers a more incremental approach to executable documentation: https://github.com/Kotlin/kotlinx-knit https://github.com/Kotlin/kotlinx-knit Neither of these approaches will result in interactive documentation.
- a6chris 3y agoI haven't used Livebook, but I think Kotlin Notebook is very similar - https://www.youtube.com/watch?v=2PLYlDJPelQ https://www.youtube.com/watch?v=2PLYlDJPelQ
- mcintyre1994 3y agoA related Elixir feature you might also find interesting is Doctests: https://elixir-lang.org/getting-started/mix-otp/docs-tests-and-with.html https://elixir-lang.org/getting-started/mix-otp/docs-tests-a... You can write inline examples in your docstrings and they’re automatically turned into unit tests. So again you get that documentation as an executable test suite not subject to rot, but at a per-function level. Same kind of idea but different levels of the documentation stack.
- mfwgenerics 3y agoThis is neat! Cheers
- troupo 3y agoI still don't understand why more languages don't have doc tests.
- mcintyre1994 3y agoI think there's two main things: - Elixir's scripting makes it super easy to write a one-liner that tests a function, that'd be a lot more verbose in many other languages - You need the docs tool and unit tests tools to 'speak the same language' to make it work, and for whatever reason Elixir devs don't seem as intent on reinventing tools like those as some other languages