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

61–70 of 72 posts

Re: Elixir Livebook is a secret weapon for documentation

#61

Post by goeiedaggoeie »

Becher19 wrote: post #58
goeiedaggoeie wrote: post #53

Earlier quoted context omitted.

thanks for the detailed answer of the differences. The interactive (I assume using CRDT's) is a good feature, jupyter server does not have this and is at a time a bit of a hassle. Also deploying it directly as an app is pretty sweet.

Livebook actually uses state reducers as described here[1]. Except for cell content. There it uses Operational Transformation. 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... [2] https://github.com/livebook-dev/livebook/blob/main/lib/liveb...

A great read, thanks so much!

Re: Elixir Livebook is a secret weapon for documentation

#62

Post by hitchstory »

Terretta wrote: post #35
hitchstory wrote: post #18

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

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 mar…

Thank you!

Re: Elixir Livebook is a secret weapon for documentation

#63

Post by krstf13 »

slorber wrote: post #60
Dowwie wrote: post #56

Earlier quoted context omitted.

Sure, here's a simple demonstration of what livebook can do that docusaurus cannot, at least without maintainer expertise ;) Imagine the following. we click a play button to start an elixir runtime based on that metadata code block with this component, we then issue commands to inspect state, manage elixir "processes" in the runtime, etc

> we click a play button to start an elixir runtime based on that metadata code block Can you show a concrete example? IE a real production url running this? What is "metadata"? In Docusaurus you can have a live playground evaluating on your browser, or you can embed any embeddable playground if it requires a server integration. > with this component, we then issue commands to inspect state, manage elixir "processes"…

Not to be rude. The live playground probably can’t run elixir/erlang code. And it most certainly cannot connect to a remote running node instance. It’s unfortunate, that the angle here is documentation since, while Livebooks are great for testing and documentation ( https://blog.appsignal.com/2022/05/24/livebook-for-elixir-ju... ), they also provide a great environment for experimenting with elixir code. I’m sure docausorus is great, I’m not sure why you would think Livebooks would be a competitor in the same space. As to you asking for in production links, I’d encourage you to install it and test it for yourself.

Re: Elixir Livebook is a secret weapon for documentation

#64

Post by Dowwie »

slorber wrote: post #60
Dowwie wrote: post #56

Earlier quoted context omitted.

Sure, here's a simple demonstration of what livebook can do that docusaurus cannot, at least without maintainer expertise ;) Imagine the following. we click a play button to start an elixir runtime based on that metadata code block with this component, we then issue commands to inspect state, manage elixir "processes" in the runtime, etc

> we click a play button to start an elixir runtime based on that metadata code block Can you show a concrete example? IE a real production url running this? What is "metadata"? In Docusaurus you can have a live playground evaluating on your browser, or you can embed any embeddable playground if it requires a server integration. > with this component, we then issue commands to inspect state, manage elixir "processes"…

here's a recent video recording of the author of Elixir showcasing some latest releases for Livebook: https://www.youtube.com/watch?v=dSjryA1iFng

The code blocks need to be run in sequence, from top-down, as one builds on the next. The "metadata" at the very top often describes the project and its dependencies.

Re: Elixir Livebook is a secret weapon for documentation

#65

Post by Dowwie »

StevenNunez wrote: post #59
Dowwie wrote: post #49

Today, in a very round-about way, one could use a livebook as if it were a blog post: download-install Livebook on your machive, download the blog post livemd file, run it locally. Here's an example. Note in the first paragraph a link to the post as a livemd file: https://genericjam.com/blog/image-processing If you go through the steps, you'll notice that the livemd isn't stylized as a blog post. This is where the ne…

Is there a way to render the livebook as read only until they try a change? I tried to open the link and it failed. I could download it and run it but I just want to see it as you intended.

There's a link on that render page to download the livebook file and run locally on your own livebook server

Re: Elixir Livebook is a secret weapon for documentation

#66

Post by rogue7 »

scurvy__dog wrote: post #42
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.

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

I managed to install it with devbox (nix under the hood), works very well !

Re: Elixir Livebook is a secret weapon for documentation

#67

Post by jljljl »

rogue7 wrote: post #66
scurvy__dog wrote: post #42

Earlier quoted context omitted.

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

I managed to install it with devbox (nix under the hood), works very well !

That's really cool! Was it as simple as running `devbox add livebook@latest`? Or did you need to configure it in any way?

Re: Elixir Livebook is a secret weapon for documentation

#68

Post by rahimnathwani »

aayushmau5 wrote: post #11
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

After reading your comment, I watched the first half of this video: https://youtu.be/4hVIxyHxwK8

Wow!

Re: Elixir Livebook is a secret weapon for documentation

#69

Post by anonyfox »

josevalim wrote: post #33
anonyfox wrote: post #22

One 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 :-/

Please open up a discussion on Livebook repo? We would love to understand more what is missing here. :)

I slightly complain a single time for the last few years, and jose directly chimes in with kind words immediately. You rock, honestly!

But on the topic: I think its a simple problem ultimately, the SF Api (https://developer.salesforce.com/docs/atlas.en-us.api_rest.m...) needs OAuth, which needs a redirect at some point, where I have no idea how to capture it from a livebook instance (easy in a phx app).

This is a reference lib in JS ( https://jsforce.github.io/ ) and there seems to be no maintained alternative on hex.pm unfortunately. So, from scratch it seems, somehow.

Additional insight: many big companies do use salesforce, and its internal tooling to produce reports/insights is rather limited, but there is a SQL-like language to do complicated stuff, but there is no way to execute a handwritten query in SF itself, except via API calls from outside. This... would be a perfect fit fro livebook! query SF + other databases to generate a report ad-hoc thats not easily possible right now without adding some heavyweight data warehouse connection!

Re: Elixir Livebook is a secret weapon for documentation

#70

Post by josevalim »

anonyfox wrote: post #69
josevalim wrote: post #33

Earlier quoted context omitted.

Please open up a discussion on Livebook repo? We would love to understand more what is missing here. :)

I slightly complain a single time for the last few years, and jose directly chimes in with kind words immediately. You rock, honestly! But on the topic: I think its a simple problem ultimately, the SF Api ( https://developer.salesforce.com/docs/atlas.en-us.api_rest.m... ) needs OAuth, which needs a redirect at some point, where I have no idea how to capture it from a livebook instance (easy in a phx app). This is a r…

I wonder if we could proxy OAuth flows to notebooks. For example, a notebook could initiate an OAuth2 flow, Livebook handles it, and once it gets back, we notify the notebook which may approve or deny the request. The biggest concern though is that we need to have a static callback URL, so you would need to run Livebook internally at a fixed address?

If this is something you would like to work on, please reach out, I think it could open up interesting possibilities!

Post reply on HN