Livebook is a secret weapon for documentation

Every application has that core, most important thing that it does. It is the reason the application exists. It’s that central idea that everything else is there to support.

A major hurdle for new developers joining a project can be understanding and becoming comfortable with the code that implements that central idea. So you document the code and may even have 100% code coverage for it.

Code documentation and tests are valuable here. Now with Livebook, there may be a new way to provide documentation, interactive exploration, and expose the app logic in a way we couldn’t before.

Livebook for App Logic?

What is Livebook?

Livebook is Elixir’s answer to something like Jupyter notebooks. It’s an exciting project created to help use Nx, Axon and machine learning with Elixir. Livebook is still early days, but it’s rapidly progressing, it’s already solid, and has some awesome features.

While it was created for the machine learning space, it isn’t limited to it. Livebook is actually really powerful even when used on a regular Phoenix web project.

Before I go any further, let me show you what I mean. Previously, I created the game TicTac that let’s you play distributed Tic-Tac-Toe with a friend from across the world on Fly.io.

Using Livebook, I documented the central piece that is the GameState. It is a module and struct used to model a game’s state. This is a glimpse of what it looks like.

Livebook accesses the project’s code and let’s me simultaneously document it and execute the code showing the results!

Why Livebook?

The important features are:

• Loads an existing Elixir project
• Code completion
• Elixir code execution
• Markdown text for explanations
• Keyboard shortcuts for easier navigation and editing
• Notebook files are stored as plain Markdown files

This means we can do the following:

1. take an existing Elixir application
2. start a notebook for the project
3. access the project’s code and document critical areas

Livebook makes it easy to experiment with our code, execute it, and demonstrate the point we’re making.

This lets developers new to a project experiment and learn that central idea. It also works for experimenting and exploring changes.

Because the notebook files are simple markdown files, they are easily added to source control and become part of the project if desired. They diff and merge well too.

Livebook is actually really powerful even when used on a regular Phoenix web project.

Let’s get started!

Livebook Setup

When Elixir 1.12 was released, Livebook was updated to require that version. It simplified things for the project and let them safely make certain assumptions. This means you need to have Elixir 1.12 installed.

Once installed, installing Livebook is this easy.

mix escript.install hex livebook

Starting Livebook is

livebook server

...
[Livebook] Application running at http://localhost:8080/?token=iphm6yeqczkyce4hzkc5ylzged6dj7kb

It gives us a URL with a randomly generated token we use to connect to our local instance. Go ahead and open it up.

Yay! We’re connected to our Livebook running locally.

Starting Tip

Since we are playing with Livebook on an existing Elixir project, start Livebook from the directory of your project. It works fine without that, starting here just makes it easier for navigating and starting the runtime. More on that later.

You’ll want your project to be using Elixir 1.12 as well.

Start a Project Notebook

Start a new notebook and name it for your project or some significant part of your project. Don’t worry though, it’s just a Markdown file and you can rename it later if you want.

Save it. When you save, select to save it to a file. Navigate to your project directory. I suggest adding a notebook directory to the name before adding your filename.

It may look something like this:

/home/youruser/my_app/notebook/overview

In this example, overview would end up named as overview.livemd.

The “notebook” directory just gives the project a home where multiple notebook files can be stored.

Connect to your Project

To connect Livebook to your project, use the “Runtime” menu item.

Using the “Runtime Settings”, select “Mix standalone”. Navigate to your Elixir project and “Connect”.

It compiles your project and starts it.

If everything goes smoothly, when you return to your notebook you can add an Elixir card and as you type, you should have code completion available using CTRL+Space or Cmd+Space.

With your code loaded, you have complete access to your application running in Livebook! In fact, you can execute Ecto queries, call contexts, start GenServers, anything!

Document Important App Logic

Now that you have Livebook setup with a new notebook and it’s connected to your your project source code, you are ready to start documenting app logic and showing what’s important!

This is what I showed earlier with the documentation and execution of the GameState module. I loved using the code completion to explore it as I documented it! It was a lot of fun writing documentation that can be interactively executed and still have all the benefits of using markdown too!

Run and Interact with GenServers

Livebook also lets you run GenServers and interact with them too!

The other main part of the TicTac application is how a GenServer runs the GameState. The running server is managed by Horde and I was able to both describe that and show it!

Livebook Tip: When working with a Livebook notebook, the keyboard shortcut you want to know is ea to “Evaluate All”. After opening a notebook, type ea and everything executes so you can see the commands and the results.

The Case for Livebook with your Project

Livebook is exciting because of what it does for Elixir in the Machine Learning space. However, Livebook can also help your regular-old Phoenix applications!

I hope you can see how Livebook can be used to document central pieces of your application in ways we never could before. Whether you’re documenting commission calculations, game logic, credit scoring, mortgage payments, or whatever. Livebook can help you do it in a new and awesome way.

Potential benefits:

• Document how critical pieces work in an interactive way
• Give new team members a better on-ramp to your project
• A place to explore changes to your central code
• Livebook is collaborative
• Connects to your project code
• Notebooks are plain markdown files and can be checked-in with the project

Give Livebook a try on your project and see how it helps your team!