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
The modules also have functions, this functions can also have their documentation but this time you use the @doc attribute to describe your function
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
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
