hopefully this will get us closer to a orgmode-ish confluence that can run any language, with CI docs test checks, and something more human than jiraql or whatever
Elixir Livebook is a secret weapon for documentation
21–30 of 72 posts
Re: Elixir Livebook is a secret weapon for documentation
#22One simple thing I need thats stopping me from jumping into Livebook fully: Salesforce API integration. Right now, I can't manage to make the auth work there (since oAuth needs some http redirect dance).
Connecting to some proper SQL database is a breeze, but if I cannot access some silo'ed data that is absilute critical, its not that useful after all :-/
Re: Elixir Livebook is a secret weapon for documentation
#23To 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.
Re: Elixir Livebook is a secret weapon for documentation
#24To 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-exp…
Oh I needed vega-lite badly in my life, thanks so much!
Re: Elixir Livebook is a secret weapon for documentation
#25I would suggest to anyone to download Livebook and test it out, even if you don't know Elixir or Erlang. You can do so much with it. I even use it for things outside of programming due to it being pretty much a markdown notebook that you can run code inside of. It's one of my favorite tools.
To do so much with it you need to know Elixir or Erlang ;)
Fwiw, I’ve been using Elixir professionally for 5 or so years and even created a few open source libraries. Never once had to touch Erlang.
Re: Elixir Livebook is a secret weapon for documentation
#26The 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 block…
A related Elixir feature you might also find interesting is Doctests: 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.
I still don't understand why more languages don't have doc tests.
Re: Elixir Livebook is a secret weapon for documentation
#27Earlier quoted context omitted.
That'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.
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…
I haven't used Livebook, but I think Kotlin Notebook is very similar - https://www.youtube.com/watch?v=2PLYlDJPelQ
Re: Elixir Livebook is a secret weapon for documentation
#28To 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-exp…
The vega-lite wrapper is very slim too, basically just converts your slithery_snake keys into humpyCamels and corrals between different data sources, so if the docs on the elixir page seem sparse its because most of the "how do I build a graph like x" is just on the vega docs. You can easily dump it to json to share too, etc.
Re: Elixir Livebook is a secret weapon for documentation
#29this is really interesting. I've never thought on using this or any jupyter-like tools to document working software. Maybe I'll try it later
Jupyter outputs to JSON. Livebook outputs to markdown, so it's more naturally renderable outside of the tool itself. There are still some rough edges -- it would be nice if livebook could cache prerendered content. for example, kino graphs only chuck a big fat JSON into a html comment, it would be nice if it also popped out an svg or encoded png with data uri.
I believe you can hover the corner of a graph and hit the (...) disclosure for a "save svg" button.
Re: Elixir Livebook is a secret weapon for documentation
#30Earlier quoted context omitted.
A related Elixir feature you might also find interesting is Doctests: 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.
I still don't understand why more languages don't have doc tests.
I 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