Writing documentation for elixir projects and serving it on localhost

Some say I am a perfectionist but I am not, I document software for me, my colleagues and the future me (you know what I mean if you ever came back to your own codebase a year later)

The main thing I learned from documenting my modules and functions was that this process makes you think more about every module and function you create, it helped me keep my functions stupidly simple. The end product is our own documentation that looks exactly like the official hex docs but for our projects

Module and function documentation

Every module you have in your application can be documented with details on what it does. To achieve this use the @moduledoc module attribute then pass it a string in markdown format. You can use this guide to learn more about markdown

Documentation for module MyApp.Hello

The modules also have functions, this functions can also have their documentation but this time you use the @doc attribute to describe your function

Function documentation

To read more on how to get started with this documentation go to the elixir guide

Generating the docs (HTML version)

After going through all the modules and functions and adding their documentation you need to generate HTML documentation that is easy to read and navigate, just like the official hexdocs

To do this you will need an elixir package ex_doc follow the link for instructions on how to set it up into your project. After the setup you can generate documentation by simply running mix docs

Running documentation in your localhost server

In our recent client project, we had a purely elixir project with no framework whatsoever so after generating the documentation as shown above we thought it would be convenient to have a mix task that when run, will generate all the documentation and serve it on our localhost:4000, so if you run mix view_docs the navigate to localhost:4000/docs/index.html you get the project documentation.

Below is a screenshot of the alias we added to our mix file

Mix aliases

Don’t worry about the other aliases, have a look at the view_docs one. It starts by generating documentation, after that it copies the documentation to the priv/static/docs folder where it can be served as static assets by plug.

Before I forget, you need to tell plug how to serve the static files in your router

plug(Plug.Static, at: “/”, from: :your_app)

For more on the configuration check on plug static documentation

Problem

I got stuck trying to implement the static files server, we never really wanted to copy the docs to the priv directory. How can we make it possible to serve directly from the generated docs directory? My guess is that it has to do with the Plug.Static but I just cannot figure out how. Have looked and tried this answer on stackoverflow but no luck.

Good thing is that we managed to get the docs working. Woohooo!!

Credit

The images on the @moduledoc and @doc are screenshots from the elixir documentation