Using ExDoc with mix

The easiest way to create documentation is to create a project using the mix tool, using a command of the form:

mix new _project_name_

Here is what it looks like when creating the documentation for the code in Example 2-4.

$ mix new combined
* creating README.md
* creating .gitignore
* creating mix.exs
* creating lib
* creating lib/combined.ex
* creating test
* creating test/test_helper.exs
* creating test/combined_test.exs

Your mix project was created successfully.
You can use "mix" to compile it, test it, and more:

    cd combined
    mix test

Run "mix help" for more commands.

Change to the combined directory and put all of your source files (for this example, combined.ex, drop.ex, and convert.ex) into the lib directory. The combined.ex file you have written before will replace the one in that mix created for you in the lib directory.

Now edit the file mix.exs so that the deps function reads as follows:

def deps do
  [{:ex_doc, github: "elixir-lang/ex_doc}]
end

Typing mix deps.get will install ExDoc in a directory named deps. If you have not yet installed Hex (Elixir’s package manager), mix will prompt you to do so. You can now compile all the Elixir files at one go using mix:

$ mix compile
==> ex_doc
Compiled lib/ex_doc/cli.ex
Compiled lib/ex_doc.ex
Compiled lib/ex_doc/markdown/cmark.ex
Compiled lib/ex_doc/markdown/earmark.ex
Compiled lib/ex_doc/markdown.ex
Compiled lib/ex_doc/markdown/hoedown.ex
Compiled lib/ex_doc/markdown/pandoc.ex
Compiled lib/mix/tasks/docs.ex
Compiled lib/ex_doc/formatter/html.ex
Compiled lib/ex_doc/retriever.ex
Compiled lib/ex_doc/formatter/html/templates.ex
Compiled lib/ex_doc/formatter/html/autolink.ex
Generated ex_doc app
==> combined
Compiled lib/convert.ex
Compiled lib/combined.ex
Compiled lib/drop.ex
Generated combined app
Consolidated List.Chars
Consolidated IEx.Info
Consolidated String.Chars
Consolidated Collectable
Consolidated Enumerable
Consolidated Inspect

You can then generate the documentation with mix docs. If you have a markdown processor installed, it should all be smooth sailing. If you don’t have markdown installed (I didn’t have it on my Linux system) you might get an error message like this:

** (RuntimeError) Could not find a markdown processor to be used on ex_doc.
You can either:

1. Add {:markdown, github: "devinus/markdown"} to your mix.exs deps
2. Ensure pandoc (http://johnmacfarlane.net/pandoc) is available in your system

In my case, the first option seemed simpler, so I changed function deps in mix.exs to:

defp deps do
  [ {:ex_doc, github: "elixir-lang/ex_doc"},
    {:markdown, github: "devinus/markdown"}]
end

I then did another mix deps.get:

* Getting markdown (git://github.com/devinus/markdown.git)
Cloning into '/Users/code/ex6-docs/combined/deps/markdown'...
remote: Reusing existing pack: 83, done.
remote: Total 83 (delta 0), reused 0 (delta 0)
Receiving objects: 100% (83/83), 12.52 KiB | 0 bytes/s, done.
Resolving deltas: 100% (34/34), done.
Checking connectivity... done.
* Getting hoedown (git://github.com/hoedown/hoedown.git)
Cloning into '/Users/code/ex6-docs/combined/deps/hoedown'...
remote: Counting objects: 1869, done.
remote: Compressing objects: 100% (805/805), done.
remote: Total 1869 (delta 1050), reused 1869 (delta 1050)
Receiving objects: 100% (1869/1869), 504.60 KiB | 481.00 KiB/s, done.
Resolving deltas: 100% (1050/1050), done.
Checking connectivity... done.

Then I re-did the mix docs, which caused the markdown processor to be compiled with the C compiler, recompiled the Elixir files, and finally created the documents. The following is the output without the compiler messages:

Compiled lib/markdown.ex
Generated markdown.app
==> combined
Compiled lib/convert.ex
Compiled lib/combined.ex
Compiled lib/drop.ex
Generated combined.app
%{green}Docs successfully generated.
%{green}View them at "doc/index.html".

Sure enough, listing the directory will now show a doc directory that contains an index.html file. The result will look like Figure B-1.

Figure B-1. Example of web page produced by ExDoc