ExDoc

ExDoc is a tool to generate documentation for your Elixir projects. To see an example, you can access Elixir's official docs.

To learn about how to document your projects, see Elixir's writing documentation page.

To see all supported options, see the documentation for mix docs.

Features

ExDoc ships with many features:

Automatically generates HTML and EPUB documents from your API documentation
Support for custom pages and guides (in addition to the API reference)
Support for custom grouping of modules, functions, and pages in the sidebar
Generates HTML documentation accessible online and offline
Responsive design with built-in layout for phones and tablets
Customizable logo on the generated documentation
Each documented entry contains a direct link back to the source code
Full-text search
Keyboard shortcuts (press ? inside an existing documentation to bring the help dialog)
Quick search with autocompletion support (s keyboard shortcut)
Go-to shortcut to take to any HexDocs package documentation with autocomplete support (g keyboard shortcut)
Support for night-mode (automatically detected according to the browser preferences)
Show tooltips when mousing over a link to a module/function (works for the current project and across projects)
A version dropdown to quickly switch to other versions (automatically configured when hosted on HexDocs)

Using ExDoc with Mix

To use ExDoc in your Mix projects, first add ExDoc as a dependency.

If you are using Elixir v1.10, or later:

def deps do
  [
    {:ex_doc, "~> 0.24", only: :dev, runtime: false},
  ]
end

If you are using Elixir v1.7, v1.8, or v1.9:

def deps do
  [
    {:ex_doc, "~> 0.22.0", only: :dev, runtime: false},
  ]
end

If you are using Elixir v1.6, or earlier:

def deps do
  [
    {:ex_doc, "~> 0.18.0", only: :dev, runtime: false},
  ]
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:

def project do
  [
    app: :my_app,
    version: "0.1.0-dev",
    deps: deps(),

    # Docs
    name: "MyApp",
    source_url: "https://github.com/USER/PROJECT",
    homepage_url: "http://YOUR_PROJECT_HOMEPAGE",
    docs: [
      main: "MyApp", # The main page in the docs
      logo: "path/to/logo.png",
      extras: ["README.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.

Using ExDoc via command line

You can ExDoc via the command line as follows:

Install ExDoc as an escript:
```
$ mix escript.install hex ex_doc
```
Then you are ready to use it in your projects. First, move into your project directory and make sure it is already compiled:
```
$ cd PATH_TO_YOUR_PROJECT
$ mix compile
```

Next invoke the ex_doc executable from your project:

$ 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

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

Using ExDoc with Erlang projects

ExDoc is capable of generating documentation from Erlang's edoc annotations through the following steps:

Use Erlang/OTP 24+
Add the following to your rebar.config. This instructs edoc to generate doc chunks instead of HTML docs:
```
{edoc_opts, [
  {doclet, edoc_doclet_chunks},
  {layout, edoc_layout_chunks},
  {dir, "_build/default/lib/<app>/doc"}]}.
```
Replace <app> with the name of your app.
Install ExDoc escript:
```
$ mix escript.install hex ex_doc
$ ex_doc --version
```
Make sure escript is in your system path, otherwise point to it directly.

Generate docs:

$ rebar3 edoc
$ ex_doc "PROJECT_NAME" "PROJECT_VERSION" _build/default/lib/<app>/ebin

If you're publishing docs to Hex.pm, first add the following to your src/<app>.app.src:
```
{doc, "doc"}
```
This instructs rebar3 to get HTML docs from the directory "doc" and that's where ExDoc would generate the docs by default.

Now you can publish your docs:
```
$ rebar3 hex docs
```
If your project has dependencies and you want to generate links to them, you need to add the dependencies to the code path.

Suppose you're building foo that depends on bar and baz. Generate the docs with:
```
$ ex_doc "foo" "1.0.0" "_build/default/lib/foo/ebin" \
    --paths "_build/default/lib/*/ebin"
```

Auto-linking

ExDoc for Elixir will automatically generate links across modules and functions if you enclose them in backticks:

By referring to a module, function, type or callback from your project, such as `MyModule`, ExDoc will automatically link to those
By referring to a module, function, type or callback from Elixir, such as `String`, ExDoc will automatically link to Elixir's stable documentation
By referring to a function, type, or callback from OTP, such as (`:queue.new/0`), ExDoc will automatically link to the OTP documentation
By referring to a module, function, type or callback from any of your dependencies, such as `MyDep`, ExDoc will automatically link to that dependency documentation on hexdocs.pm (the link can be configured by setting docs: [deps: [my_dep: "https://path/to/docs/"]] in your mix.exs)

ExDoc supports linking to modules (`MyModule`), functions (`MyModule.function/1`), types (`t:MyModule.type/2`) and callbacks (`c:MyModule.callback/3`). If you want to link a function, type or callback in the current module, you may skip the module name, such as `function/1`.

You can also use a custom text, e.g.: [custom text](`MyModule.function/1`). This also allows to refer to OTP modules, e.g.: [`:array`](`:array`).

Link to extra pages like this: [Up and running](Up and running.md) (skipping the directory the page is in), the final link will be automatically converted to up-and-running.html.

Extensions

ExDoc renders Markdown content for you, but you can extend it to render complex objects on the page using JavaScript. To inject custom JavaScript into every page, add this to your configuration:

docs: [
  # ...
  before_closing_body_tag: &before_closing_body_tag/1
]

# ...

defp before_closing_body_tag(:html) do
  """
  <!-- HTML injected at the end of the <body> element -->
  """
end

defp before_closing_body_tag(_), do: ""

Rendering Math

If you write TeX-style math in your Markdown (like $\sum_{i}^{N} x_i$ ), they end up as raw text on the generated pages. To render them we recommend using KaTeX, a JavaScript library that turns those expressions into actual graphics. To load and trigger KaTeX on every documentation page we can insert the following HTML:

<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/katex@0.13.19/dist/katex.min.css" integrity="sha384-beuqjL2bw+6DBM2eOpr5+Xlw+jiH44vMdVQwKxV28xxpoInPHTVmSvvvoPq9RdSh" crossorigin="anonymous">
<script defer src="https://cdn.jsdelivr.net/npm/katex@0.13.19/dist/katex.min.js" integrity="sha384-aaNb715UK1HuP4rjZxyzph+dVss/5Nx3mLImBe9b0EW4vMUkc1Guw4VRyQKBC0eG" crossorigin="anonymous"></script>
<script defer src="https://cdn.jsdelivr.net/npm/katex@0.13.19/dist/contrib/auto-render.min.js" integrity="sha384-+XBljXPPiv+OzfbB3cVmLHf4hdUFHlWNZN5spNQ7rmHTXpd7WvJum6fIACpNNfIR" crossorigin="anonymous"
    onload="renderMathInElement(document.body);"></script>

For more details and configuration options see the KaTeX Auto-render Extension.

Rendering Vega-Lite plots

Other objects you may want to render in a special manner are code snippets. For example, assuming your Markdown includes Vega-Lite specification in vega-lite code snippets, you can do:

<script src="https://cdn.jsdelivr.net/npm/vega@5.20.2"></script>
<script src="https://cdn.jsdelivr.net/npm/vega-lite@5.1.1"></script>
<script src="https://cdn.jsdelivr.net/npm/vega-embed@6.18.2"></script>
<script>
  document.addEventListener("DOMContentLoaded", function () {
    for (const codeEl of document.querySelectorAll("pre code.vega-lite")) {
      try {
        const preEl = codeEl.parentElement;
        const spec = JSON.parse(codeEl.textContent);
        const plotEl = document.createElement("div");
        preEl.insertAdjacentElement("afterend", plotEl);
        vegaEmbed(plotEl, spec);
        preEl.remove();
      } catch (error) {
        console.log("Failed to render Vega-Lite plot: " + error)
      }
    }
  });
</script>

For more details and configuration options see the vega/vega-embed.

Contributing

The easiest way to test changes to ExDoc is to locally rebuild the app and its own documentation:

Run mix setup to install all dependencies
Run mix build to generate docs. This is a custom alias that will build assets, recompile ExDoc, and output fresh docs into the doc/ directory
If you want to contribute a pull request, please do not add to your commits the files generated in the assets/ and formatters/ folders
Run mix lint to check if the Elixir and JavaScript files are properly formatted. You can run mix fix to let the JavaScript linter and Elixir formatter fix the code automatically before submitting your pull request

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.

Any documentation generated by ExDoc, or any documentation generated by any "Derivative Works" (as specified in the Apache 2 License), must include a direct, readable, and visible link to the ExDoc repository on each rendered material. For HTML pages, a rendered material represents every single page. For PDF, EPUB and other ebook formats, it means one entry for the whole material.

Qizot / ex_doc