Our great sponsors
-
hitchstory
Type-safe YAML integration tests. Tests that write your docs. Tests that rewrite themselves.
-
-
WorkOS
The modern identity platform for B2B SaaS. The APIs are flexible and easy-to-use, supporting authentication, user identity, and complex enterprise features like SSO and SCIM provisioning.
-
-
-
-
-
InfluxDB
Power Real-Time Data Analytics at Scale. Get real-time insights from all types of time series data with InfluxDB. Ingest, query, and analyze billions of data points in real-time with unbounded cardinality.
-
explorer
Series (one-dimensional) and dataframes (two-dimensional) for fast and elegant data exploration in Elixir
-
This is incredible work.
To anyone curious, I highly recommend:
- https://hitchdev.com/hitchstory/approach/
- https://hitchdev.com/hitchstory/why-not/
From the overall RDD/BDD type home page:
- https://hitchdev.com/hitchstory/
The entire product site is a thing of richly informative beauty.
---
My only question was whether the generated 'docs' snippets would add value over just reading the story in your DASL. Any markdown site generator (such as the chosen Material for MKDocs) can just embed the ```yaml anyway. But then I realized what was generating e.g. …
- https://hitchdev.com/hitchstory/using/engine/rewrite-story/
… and how superior that is to typical docs, especially typical docstring or swagger factories.
For linux the easiest way to download livebook is with docker [1] or maybe with fly.io [2].
Installing it directly is a bit complicated if you are not familiar with it. I wish linux also had Desktop app like mac.
[1]: https://github.com/livebook-dev/livebook#docker
[2]: https://fly.io/launch/livebook
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
This concept sounds quite a bit like the usage of .mdx files in OCaml. Those are markdown files which can load and execute OCaml code in them.
They are useful for unit testing code like libraries, providing usage examples for end-users (as well as the text format markdown usually supports) and testing it at the same time. Definitely a great idea for documentation, and one which I should use more of.
https://github.com/realworldocaml/mdx
That 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
Apart from running code inside a "markdown" file, livebook can do much more. You have Smart cells to show charts, run sql queries against a db, run Neural Network tasks such as Image-To-Text generation using Bumblebee[1], etc. It is collaborative as well.
[1] https://github.com/elixir-nx/bumblebee
To ensure you do not miss this: LiveBook comes with a Vega Lite integration (https://livebook.dev/integrations -> https://livebook.dev/integrations/vega-lite/), which means you get access to a lot of visualisations out of the box, should you need that (https://vega.github.io/vega-lite/).
In the same "standing on giant's shoulders" stance, you can use Explorer (see example LiveBook at https://github.com/elixir-explorer/explorer/blob/main/notebo...), which leverages Polars (https://www.pola.rs), a very fast DataFrame library and now a company (https://www.pola.rs/posts/company-announcement/) with 4M$ seed.
To ensure you do not miss this: LiveBook comes with a Vega Lite integration (https://livebook.dev/integrations -> https://livebook.dev/integrations/vega-lite/), which means you get access to a lot of visualisations out of the box, should you need that (https://vega.github.io/vega-lite/).
In the same "standing on giant's shoulders" stance, you can use Explorer (see example LiveBook at https://github.com/elixir-explorer/explorer/blob/main/notebo...), which leverages Polars (https://www.pola.rs), a very fast DataFrame library and now a company (https://www.pola.rs/posts/company-announcement/) with 4M$ seed.
For NodeJS enthusiasts, Check out Docusaurus (by Meta).
For Markdown Docs, Markdown Blogs, and JSX-static pages
- https://docusaurus.io
- https://docusaurus.io/docs/next/api/themes/@docusaurus/theme...
The source code[2] is really instructional and easy to understand. I highly recommend to look into it :)
[1] https://github.com/jonatanklosko/notebooks/blob/main/article...