Introducing Elixir: Getting Started in Functional Programming (2014)
Appendix B. Generating Documentation with ExDoc
In Chapter 2, you learned how to add documentation to your programs. The ExDoc tool takes that documentation and produces nicely formatted reference documentation in web page format. ExDoc works in conjunction with Mix, a tool for creating, compiling, and testing projects.You can find out more about Mix in Chapter 12.
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. 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.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/retriever.ex
Compiled lib/ex_doc/formatter/html/autolink.ex
Compiled lib/ex_doc/formatter/html.ex
Compiled lib/ex_doc/formatter/html/templates.ex
Generated ex_doc.app
==> combined
Compiled lib/convert.ex
Compiled lib/drop.ex
Compiled lib/combined.ex
Generated combined.app
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 "docs/index.html".
Sure enough, listing the directory will now show a docs 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