Java has Javadoc, Ruby has RDoc, and Elixir has ExDoc—a documentation tool that describes your project, showing the modules, the things defined in them, and any documentation you’ve written for them.
Using it is easy. First, add the ExDoc dependency to your mix.exs file. You’ll also need to add an output formatter—I use earmark, a pure-Elixir Markdown-to-HTML convertor.
| | defp deps do |
| | [ |
| | { :httpoison, "~> 1.0.0" }, |
| | { :poison, "~> 3.1.0" }, |
| | { :ex_doc, "~> 0.18.1" }, |
| | { :earmark, "~> 1.2.4" }, |
| | ] |
| | end |
While you’re in the mix.exs, you can add a project name and (if your project is in GitHub) a URL. The latter allows ExDoc to provide live links to your source code. These parameters go in the project function:
| | def project do |
| | [ app: :issues, |
| | version: "0.0.1", |
| » | name: "Issues", |
| » | source_url: "https://github.com/pragdave/issues", |
| | deps: deps ] |
| | end |
Then run mix deps.get.
To generate the documentation, just run
| | $ mix docs |
| | Docs generated with success. |
| | Open up docs/index.html in your browser to read them. |
The first time you run this task, it will install ExDoc. That involves compiling some C code, so you’ll need a development environment on your machine.
Open docs/index.html in your browser, then use the sidebar on the left to search or drill down through your modules. Here’s what I see for the start of the documentation for TableFormatter:
And that’s it. The full project is in the source download at project/5/issues.