Hacker News Board Hacker News, browsed like a classic message board
Live data from Hacker News

Elixir Livebook is a secret weapon for documentation

fly.io

Post reply on HN
Print view View original

11–20 of 72 posts

Re: Elixir Livebook is a secret weapon for documentation

#11

Post by aayushmau5 »

zogrodea wrote: post #7

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.co…

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

Re: Elixir Livebook is a secret weapon for documentation

#12

Post by rapnie »

zogrodea wrote: post #7

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.co…

Yes, more uptake of mdx in general. E.g. I use Astro static site generator and they offer it too.

https://docs.astro.build/en/guides/markdown-content/

Re: Elixir Livebook is a secret weapon for documentation

#13

Post by mfwgenerics »

mcintyre1994 wrote: post #10
mfwgenerics wrote: post #4

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 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.

This is neat! Cheers

Re: Elixir Livebook is a secret weapon for documentation

#14

Post by impulser_ »

troupo wrote: post #9
impulser_ wrote: post #6

I 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 ;)

You actually don't. You can use smart cells which lets you do a lot without actually coding. You can transform data, build charts, run AI model and more all without writing code.

You might have to Google how to read a file in Elixir, but you don't actually need to know Elixir.

In the future, you won't even need to know that to use it.

Re: Elixir Livebook is a secret weapon for documentation

#15

Post by troupo »

impulser_ wrote: post #14
troupo wrote: post #9

Earlier quoted context omitted.

To do so much with it you need to know Elixir or Erlang ;)

You actually don't. You can use smart cells which lets you do a lot without actually coding. You can transform data, build charts, run AI model and more all without writing code. You might have to Google how to read a file in Elixir, but you don't actually need to know Elixir. In the future, you won't even need to know that to use it.

Ah. I never actually looked into smart cells.

Mind blown.gif

:)

Re: Elixir Livebook is a secret weapon for documentation

#17

Post by disgruntledphd2 »

theCodeStig wrote: post #16

Org-babel can do a lot of this, no?

Yeah but to be fair, it's a bit gnarly to get set up and it can't do interactive graphs.

Don't get me wrong, I love org babel but there are some advantages of the browser based approach.

Re: Elixir Livebook is a secret weapon for documentation

#18

Post by hitchstory »

While I'm glad the idea of tying documentation to tests is catching on, I think markdown documentation -> create tests is the wrong way around.

I built this tool to let people generate evergreen markdown documentation from annotated type-safe YAML integration tests:

https://github.com/hitchdev/hitchstory

Re: Elixir Livebook is a secret weapon for documentation

#19

Post by YousefED »

If you're interested in this hybrid of docs and live coding, I'm building something similar for the Typescript / Javascript / React ecosystem @ https://www.typecell.org (open source). See https://twitter.com/YousefED/status/1677342430545301504 for a preview of the next version which will be more "wysiwyg" than the current notebook environment

Re: Elixir Livebook is a secret weapon for documentation

#20

Post by theCodeStig »

disgruntledphd2 wrote: post #17
theCodeStig wrote: post #16

Org-babel can do a lot of this, no?

Yeah but to be fair, it's a bit gnarly to get set up and it can't do interactive graphs. Don't get me wrong, I love org babel but there are some advantages of the browser based approach.

You’re right. I love emacs, though I must admit it’s quite a barrier to entry
Post reply on HN