When creating an OpenSource library and hosting it on hex.pm,
you should provide documentation. Mix comes with
mix hex.publish docs
to help make that easy. However, what if you want to use the same documentation
tools for a non-published Phoenix project?
Updated Nov 2016 for information on using in an umbrella app and more.
ExDoc is a documentation generation tool for Elixir
ExDoc generates web documentation for any elixir project and that includes your phoenix applications.
So use it already
Add it to your project but only for the dev environment.
Install the package…
Oddly, the new
mix docs mix task may not show up yet in
mix --help. It
didn’t for me. Go ahead and run it anyway. Once you do, it will show up in the
Now it shows up as expected.
What did it do?
It created a new
doc folder at the project root and created lots of files.
The important file is
doc/index.html. Open that in your browser to access the
Hide some of those modules
With a Phoenix app, you may end up with a lot of modules being documented that you don’t want to document and otherwise clutter up the information you are trying to convey.
@moduledoc false will not only tell ExDoc you don’t want to provide
documentation for the module, it will completely suppress it from the generated
The same holds true with
@doc false for suppressing a function from the
After sprinkling around a little
@moduledoc false here and there, it cleaned up well. Here’s a sample new Phoenix project’s ExDoc docs.
Add your readme and other markdown files
ExDoc supports adding “extras” to your documentation project. This can include your readme and any other markdown files you create. Some suggestions to consider:
- GettingStarted.md - file for onboarding new team members
- guides/testing.md - guide for how to test the application (does it require chromedriver? hound? special setup?)
- README.md - the project’s readme file that hopefully has useful information in it
- CONTRIBUTING.md - information on how to contribute to the project
You customize the ExDoc settings in your
mix.exs project file under the
section. (At the bottom)
docs section added at the bottom adds the project’s readme file.
The readme shows up in the “Pages” section of the generated documentation. You
can list any set of other files you want included in the documentation here as
well. In the example above I link to a “custom_page.md” file in the “markdown”
In the docs function, I show the
source_url option. This feature understands
Github and adds a “</>” link to the documentation for a function or module
linking directly to that page in your Github Repo. Slick!
Note: If you link to code that isn’t on master yet (a branch or local development), then the generated link will 404.
In an Umbrella
ExDoc works well when in an umbrella app too. You can run
mix docs at the
umbrella project root and it runs it for each project. Note that it doesn’t
create a single combined doc, but docs for each project in the umbrella.
In an umbrella, you need to update the source_url to link deeper to the specific app in the umbrella. Fortunately this is supported too!
In your documentation, when referencing a module or function, if you give it a
fully qualified name in back ticks like
List.delete_all/2, ExDocs will turn that into a link
for you. Note to include a function’s arrity.
Some resources to start you off in best-practices for writing your docs.
- elixir-lang.org/docs/master/elixir/writing-documentation.html - the official source for writing Elixir project documentation
- elixir-lang.org/docs/stable/elixir/Module.html - information on supported module attributes
- elixirschool.com/lessons/basics/documentation/ - a nice introductory guide
ExDoc is a great tool for building good-looking, hassle-free documentation for your Elixir and Phoenix projects. It is up to you if you want the generated files to be committed to your git repository or ignored. Either way, it is a powerful tool to help your team share knowledge and project information.
See ExDoc on GitHub or
mix help docs
for more usage information.
What tips or tricks do you have for project documentation?