Packages
ex_doc
0.14.1
0.40.3
0.40.2
0.40.1
0.40.0
0.39.3
0.39.2
0.39.1
0.39.0
0.38.4
0.38.3
0.38.2
0.38.1
0.38.0
0.37.3
0.37.2
0.37.1
0.37.0
0.37.0-rc.2
0.37.0-rc.1
0.37.0-rc.0
0.36.1
0.36.0
0.35.1
0.35.0
0.34.2
0.34.1
0.34.0
0.33.0
0.32.2
0.32.1
0.32.0
0.31.2
0.31.1
0.31.0
0.30.9
0.30.8
0.30.7
0.30.6
0.30.5
0.30.4
0.30.3
0.30.2
0.30.1
0.30.0
0.29.4
0.29.3
0.29.2
0.29.1
0.29.0
0.28.6
0.28.5
0.28.4
0.28.3
0.28.2
0.28.1
0.28.0
0.27.3
0.27.2
0.27.1
0.27.0
0.26.0
0.25.5
0.25.4
0.25.3
0.25.2
0.25.1
0.25.0
0.24.2
0.24.1
0.24.0
0.23.0
0.22.6
0.22.5
0.22.4
0.22.2
0.22.1
0.22.0
0.21.3
0.21.2
0.21.1
0.21.0
0.20.2
0.20.1
0.20.0
0.19.3
0.19.2
0.19.1
0.19.0
0.19.0-rc
0.18.4
0.18.3
0.18.2
0.18.1
0.18.0
retired
0.17.1
0.17.0
retired
0.16.4
0.16.3
0.16.2
0.16.1
0.16.0
0.15.1
0.15.0
0.14.5
0.14.4
0.14.3
0.14.2
0.14.1
0.14.0
0.13.2
0.13.1
0.13.0
0.12.0
0.11.5
0.11.4
0.11.3
0.11.2
0.11.1
0.11.0
0.10.0
0.9.0
0.8.4
0.8.3
0.8.2
0.8.1
0.8.0
0.7.3
0.7.2
0.7.1
0.7.0
0.6.2
0.6.1
0.6.0
0.5.2
0.5.1
ExDoc is a documentation generation tool for Elixir
Current section
Files
Jump to
Current section
Files
README.md
# ExDoc
[][build-status]
[][coverage-status]
ExDoc is a tool to generate documentation for your Elixir projects. In case you are looking for documentation for Elixir itself, [check out Elixir's website][elixir-lang].
## Using ExDoc with Mix
To use ExDoc in your Mix projects, first add ExDoc as a dependency:
```elixir
def deps do
[{:ex_doc, "~> 0.14", only: :dev}]
end
```
After adding ExDoc as a dependency, run `mix deps.get` to install it.
ExDoc will automatically pull in information from your projects, like the application and version. However, you may want to set `:name`, `:source_url` and `:homepage_url` to have a nicer output from ExDoc, such as:
```elixir
def project do
[app: :my_app,
version: "0.1.0-dev",
deps: deps(),
# Docs
name: "My App",
source_url: "https://github.com/USER/PROJECT",
homepage_url: "http://YOUR_PROJECT_HOMEPAGE",
docs: [logo: "path/to/logo.png",
canonical: "https://hexdocs.com/PROJECT"
extras: ["README.md", "CONTRIBUTING.md"]]]
end
```
Now you are ready to generate your project documentation with `mix docs`.
To see all options available when generating docs, run `mix help docs`. You may have to do `mix docs` or `mix deps.compile` first.
## Using ExDoc via command line
You can ExDoc via the command line as follows:
1. First clone and compile it:
```console
$ git clone https://github.com/elixir-lang/ex_doc.git
$ cd ex_doc
$ mix do deps.get, compile
```
2. Then you are ready to use it in your projects. First, move into your project directory and make sure it is already compiled:
```console
$ cd PATH_TO_YOUR_PROJECT
$ mix compile
```
3. Next invoke the ex_doc executable from your project:
```console
$ PATH_TO_YOUR_EXDOC/bin/ex_doc "PROJECT_NAME" "PROJECT_VERSION" path/to/project/ebin -m "PROJECT_MODULE" -u "https://github.com/GITHUB_USER/GITHUB_REPO" -l path/to/logo.png
```
4. By default, ex_doc produces HTML files, but, you can also create a EPUB document passing the option `--formatter epub`:
```console
$ PATH_TO_YOUR_EXDOC/bin/ex_doc "PROJECT_NAME" "PROJECT_VERSION" path/to/project/ebin -m "PROJECT_MODULE" -u "https://github.com/GITHUB_USER/GITHUB_REPO" -l path/to/logo.png -f epub
```
For example, here are some acceptable values:
PROJECT_NAME => Ecto
PROJECT_VERSION => 0.1.0
PROJECT_MODULE => Ecto (the main module provided by the library)
GITHUB_USER => elixir-lang
GITHUB_REPO => ecto
## Changing the Markdown tool
In the examples above, we have used [Earmark][] to convert Markdown to HTML. If you prefer, you can also use pandoc, hoedown (in C), or cmark (in C).
### Pandoc
Install [pandoc][] using whichever means is right for your system. Odds are good it is available via whatever package manager you have available to you.
Update your project configuration to use pandoc:
```elixir
config :ex_doc, :markdown_processor, ExDoc.Markdown.Pandoc
```
### Hoedown
Hoedown is a standard compliant Markdown parser written in C. To use hoedown, add the elixir NIF wrapper [markdown][devinus/markdown] as a dependency to your project:
```elixir
{:markdown, github: "devinus/markdown"}
```
Update your project configuration to use hoedown:
```elixir
config :ex_doc, :markdown_processor, ExDoc.Markdown.Hoedown
```
### Cmark
[Cmark][cmark] is a CommonMark parser written in C. To use cmark add the elixir NIF wrapper [cmark.ex][cmark.ex] as a dependency to your project:
```elixir
{:cmark, "~> 0.6", only: :dev}
```
Update your project configuration to use Cmark:
```elixir
config :ex_doc, :markdown_processor, ExDoc.Markdown.Cmark
```
# License
ExDoc source code is released under Apache 2 License. The generated contents, however, are under different licenses based on projects used to help render HTML, including CSS, JS, and other assets.
Check the [LICENSE](LICENSE) file for more information.
[coverage-status]: https://coveralls.io/github/elixir-lang/ex_doc?branch=master
[build-status]: http://travis-ci.org/elixir-lang/ex_doc
[earmark]: http://github.com/pragdave/earmark
[elixir-lang]: http://elixir-lang.org/
[pandoc]: http://johnmacfarlane.net/pandoc/
[cmark]: https://github.com/jgm/cmark
[cmark.ex]: https://github.com/asaaki/cmark.ex
[devinus/markdown]: http://github.com/devinus/markdown