README.md (13547B)
1 # ExDoc 2 3 [![Build Status](https://github.com/elixir-lang/ex_doc/workflows/CI/badge.svg)](https://github.com/elixir-lang/ex_doc/actions?query=workflow%3A%22CI%22) 4 [![Coverage Status](https://coveralls.io/repos/github/elixir-lang/ex_doc/badge.svg?branch=master)](https://coveralls.io/github/elixir-lang/ex_doc?branch=master) 5 6 ExDoc is a tool to generate documentation for your Elixir projects. To see an example, [you can access Elixir's official docs](https://hexdocs.pm/elixir/). 7 8 To learn about how to document your projects, see [Elixir's writing documentation page](https://hexdocs.pm/elixir/writing-documentation.html). 9 10 To see all supported options, see the documentation for [mix docs](https://hexdocs.pm/ex_doc/Mix.Tasks.Docs.html). 11 12 ## Features 13 14 ExDoc ships with many features: 15 16 * Automatically generates HTML and EPUB documents from your API documentation 17 * Responsive design with built-in layout for phones and tablets 18 * Support for custom pages, guides, and livebooks (in addition to the API reference) 19 * Support for custom grouping of modules, functions, and pages in the sidebar 20 * Generates HTML documentation accessible online and offline 21 * Customizable logo on the generated documentation 22 * Each documented entry contains a direct link back to the source code 23 * Full-text search 24 * Keyboard shortcuts (press `?` inside an existing documentation to bring the help dialog) 25 * Quick search with autocompletion support (`s` keyboard shortcut) 26 * Go-to shortcut to take to any HexDocs package documentation with autocomplete support (`g` keyboard shortcut) 27 * Support for night-mode (automatically detected according to the browser preferences) 28 * Show tooltips when mousing over a link to a module/function (works for the current project and across projects) 29 * A version dropdown to quickly switch to other versions (automatically configured when hosted on HexDocs) 30 31 ## Usage 32 33 You can use ExDoc with Mix (recommended for Elixir projects), with Rebar (recommended for Erlang projects), or via the command line. 34 35 ### Using ExDoc with Mix 36 37 First add ExDoc as a dependency. ExDoc requires Elixir v1.10 or later: 38 39 ```elixir 40 def deps do 41 [ 42 {:ex_doc, "~> 0.27", only: :dev, runtime: false}, 43 ] 44 end 45 ``` 46 47 Then run `mix deps.get` to install it. 48 49 > #### Erlang development environment {: .warning} 50 > 51 > Some Operating System distributions split Erlang into multiple packages and at least one ExDoc dependency (`earmark_parser`) requires Erlang development environment. If you get a message like "/usr/lib/erlang/lib/parsetools-2.3.1/include/yeccpre.hrl: no such file or directory", it means you lack this environment. For instance, on the Debian operating system and its derivatives, you need to `apt install erlang-dev`. 52 53 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: 54 55 ```elixir 56 def project do 57 [ 58 app: :my_app, 59 version: "0.1.0-dev", 60 deps: deps(), 61 62 # Docs 63 name: "MyApp", 64 source_url: "https://github.com/USER/PROJECT", 65 homepage_url: "http://YOUR_PROJECT_HOMEPAGE", 66 docs: [ 67 main: "MyApp", # The main page in the docs 68 logo: "path/to/logo.png", 69 extras: ["README.md"] 70 ] 71 ] 72 end 73 ``` 74 75 Now you are ready to generate your project documentation with `mix docs`. To see all options available when generating docs, run `mix help docs`. 76 77 ### Using ExDoc with Rebar3 78 79 From Erlang/OTP 24+, you can use ExDoc to render your Erlang documentation written with EDoc. See [`rebar3_ex_doc`](https://github.com/starbelly/rebar3_ex_doc/) for more information. 80 81 ### Using ExDoc via command line 82 83 You can ExDoc via the command line as follows: 84 85 1. Install ExDoc as an escript: 86 87 ```bash 88 $ mix escript.install hex ex_doc 89 ``` 90 91 2. Then you are ready to use it in your projects. First, move into your project directory and make sure it is already compiled: 92 93 ```bash 94 $ cd PATH_TO_YOUR_PROJECT 95 $ mix compile 96 ``` 97 98 3. Next invoke the `ex_doc` executable from your project: 99 100 ```bash 101 $ ex_doc "PROJECT_NAME" "PROJECT_VERSION" _build/dev/lib/project/ebin -m "PROJECT_MODULE" -u "https://github.com/GITHUB_USER/GITHUB_REPO" -l path/to/logo.png 102 ``` 103 104 For example, here are some acceptable values: 105 106 PROJECT_NAME => Ecto 107 PROJECT_VERSION => 0.1.0 108 PROJECT_MODULE => Ecto (the main module provided by the library) 109 GITHUB_USER => elixir-lang 110 GITHUB_REPO => ecto 111 112 ## Syntax highlighting 113 114 ExDoc uses [the makeup project](https://github.com/elixir-makeup/makeup) for syntax highlighting. By default, it includes highlighters for Erlang and Elixir. To highlight other languages, simply add the equivalent `makeup_LANGUAGE` package to your `mix.exs`/`rebar.config`. For example, for HTML support, you could add: 115 116 ```elixir 117 {:makeup_html, ">= 0.0.0", only: :dev, runtime: false} 118 ``` 119 120 You can find all support languages [under the Makeup organization on GitHub](https://github.com/elixir-makeup) and [view them on Makeup's website](https://elixir-makeup.github.io/makeup_demo/). 121 122 ## Metadata 123 124 ExDoc supports metadata keys in your documentation. For example, the `since` metadata is used to annotate from when a given module/function is available. In Elixir, you can add metadata to modules and functions, respectively, like this: 125 126 ```elixir 127 @moduledoc since: "1.10.0" 128 @doc since: "1.13.1" 129 ``` 130 131 In Erlang's EDoc, you would do: 132 133 ```erlang 134 %% @since 0.1.0 135 ``` 136 137 The following metadata is available for both modules and functions: 138 139 * `deprecated` (string) - marks the given module/function as deprecated with the given string as reason 140 * `since` (string) - annotates the given module/function is available from a particular version 141 142 The following metadata is available for modules: 143 144 * `tags` (list of atoms) - a list of strings to be added as tags to the module (not supported by EDoc) 145 146 ## Auto-linking 147 148 ExDoc for Elixir will automatically generate links across modules and functions if you enclose them in backticks: 149 150 * By referring to a module, function, type or callback from your project, such as `` `MyModule` ``, ExDoc will automatically link to those 151 * By referring to a module, function, type or callback from Elixir, such as `` `String` ``, ExDoc will automatically link to Elixir's stable documentation 152 * By referring to a function, type, or callback from OTP, such as (`` `:queue.new/0` ``), ExDoc will automatically link to the OTP documentation 153 * 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](https://hexdocs.pm/) (the link can be configured by setting `docs: [deps: [my_dep: "https://path/to/docs/"]]` in your `mix.exs`) 154 155 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` ``. 156 157 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`) ``. 158 159 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`. 160 161 ## Admonition blocks 162 163 You may want to draw attention to certain statements by taking them out of the content's flow and labeling them with a priority. These are called admonitions, sometimes are also known as asides or callouts. An admonition block is rendered based on the assigned label or class. `ex_doc` supports the following tags: `warning`, `error`, `info`, `tip`, and `neutral` over header levels `h3` and `h4`. 164 165 The syntax is as follows: 166 167 > #### Error {: .error} 168 > 169 > This syntax will render an error block 170 171 The result for the previous syntax is as follows: 172 173 > #### Error {: .error} 174 > 175 > This syntax will render an error block 176 177 For example, if you change the class name to `neutral`, you get the same admonition block in neutral style: 178 179 > #### Error {: .neutral} 180 > 181 > This syntax will render an error block 182 183 ## Extensions 184 185 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: 186 187 ```elixir 188 docs: [ 189 # ... 190 before_closing_body_tag: &before_closing_body_tag/1 191 ] 192 193 # ... 194 195 defp before_closing_body_tag(:html) do 196 """ 197 <!-- HTML injected at the end of the <body> element --> 198 """ 199 end 200 201 defp before_closing_body_tag(_), do: "" 202 ``` 203 204 ### Rendering Math 205 206 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](https://katex.org/), 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: 207 208 ```html 209 <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"> 210 <script defer src="https://cdn.jsdelivr.net/npm/katex@0.13.19/dist/katex.min.js" integrity="sha384-aaNb715UK1HuP4rjZxyzph+dVss/5Nx3mLImBe9b0EW4vMUkc1Guw4VRyQKBC0eG" crossorigin="anonymous"></script> 211 <script defer src="https://cdn.jsdelivr.net/npm/katex@0.13.19/dist/contrib/auto-render.min.js" integrity="sha384-+XBljXPPiv+OzfbB3cVmLHf4hdUFHlWNZN5spNQ7rmHTXpd7WvJum6fIACpNNfIR" crossorigin="anonymous" 212 onload="renderMathInElement(document.body);"></script> 213 ``` 214 215 For more details and configuration options see the [KaTeX Auto-render Extension](https://katex.org/docs/autorender.html). 216 217 ### Rendering Vega-Lite plots 218 219 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: 220 221 ```html 222 <script src="https://cdn.jsdelivr.net/npm/vega@5.20.2"></script> 223 <script src="https://cdn.jsdelivr.net/npm/vega-lite@5.1.1"></script> 224 <script src="https://cdn.jsdelivr.net/npm/vega-embed@6.18.2"></script> 225 <script> 226 document.addEventListener("DOMContentLoaded", function () { 227 for (const codeEl of document.querySelectorAll("pre code.vega-lite")) { 228 try { 229 const preEl = codeEl.parentElement; 230 const spec = JSON.parse(codeEl.textContent); 231 const plotEl = document.createElement("div"); 232 preEl.insertAdjacentElement("afterend", plotEl); 233 vegaEmbed(plotEl, spec); 234 preEl.remove(); 235 } catch (error) { 236 console.log("Failed to render Vega-Lite plot: " + error) 237 } 238 } 239 }); 240 </script> 241 ``` 242 243 For more details and configuration options see [vega/vega-embed](https://github.com/vega/vega-embed). 244 245 ### Rendering Mermaid graphs 246 247 Similarly to the example above, if your Markdown includes Mermaid graph specification in `mermaid` code snippets, you can do: 248 249 ```html 250 <script src="https://cdn.jsdelivr.net/npm/mermaid@8.13.3/dist/mermaid.min.js"></script> 251 <script> 252 document.addEventListener("DOMContentLoaded", function () { 253 mermaid.initialize({ startOnLoad: false }); 254 let id = 0; 255 for (const codeEl of document.querySelectorAll("pre code.mermaid")) { 256 const preEl = codeEl.parentElement; 257 const graphDefinition = codeEl.textContent; 258 const graphEl = document.createElement("div"); 259 const graphId = "mermaid-graph-" + id++; 260 mermaid.render(graphId, graphDefinition, function (svgSource, bindListeners) { 261 graphEl.innerHTML = svgSource; 262 bindListeners && bindListeners(graphEl); 263 preEl.insertAdjacentElement("afterend", graphEl); 264 preEl.remove(); 265 }); 266 } 267 }); 268 </script> 269 ``` 270 271 For more details and configuration options see the [Mermaid usage docs](https://mermaid-js.github.io/mermaid/#/usage). 272 273 ## Contributing 274 275 The easiest way to test changes to ExDoc is to locally rebuild the app and its own documentation: 276 277 1. Run `mix setup` to install all dependencies 278 2. 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 279 3. If you want to contribute a pull request, please do not add to your commits the files generated in the `formatters/` directory 280 4. Run `mix lint` to check if the Elixir and JavaScript files are properly formatted. 281 You can run `mix fix` to let the JavaScript linter and Elixir formatter fix the code automatically before submitting your pull request 282 283 If working on the assets, please see the README in the `assets/` directory. 284 285 The build process is currently tested in Node 16 LTS. 286 287 ## License 288 289 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. 290 291 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](https://github.com/elixir-lang/ex_doc) 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.