ExDoc produces HTML and EPUB documentation for Elixir projects (Evacuated from NSA/Microsoft Github)
You can not select more than 25 topics Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
 
 
 
 
 
@jeffcliff@shitposter.club d58efe9937 degithubbing part 1 3 months ago
assets Link directly to page if sidebar item has no subitems (#855) 5 years ago
bin Make ExDoc work as an escript (#651) 6 years ago
formatters Migrate to npm from yarn 5 years ago
lib Autolink "/" function (#850) 5 years ago
test Autolink "/" function (#850) 5 years ago
.ebert.yml Reenable eslint and a single rule to allow external parsing 6 years ago
.eslintrc Pass ecmaVersion instead of turning on features individually 6 years ago
.gitattributes Remove assets from priv (#785) 5 years ago
.gitignore Include formatters directory in package 5 years ago
.travis.yml Run npm install 5 years ago
CHANGELOG.md Release v0.18.3 5 years ago
LICENSE Update LICENSE (#623) 6 years ago
README.md degithubbing part 1 3 months ago
gulpfile.js Migrate to npm from yarn 5 years ago
mix.exs Migrate to npm from yarn 5 years ago
mix.lock Remove built-in support for hoedown 5 years ago
package-lock.json Migrate to npm from yarn 5 years ago
package.json Migrate to npm from yarn 5 years ago

README.md

ExDoc

ExDoc is a tool to generate documentation for your Elixir projects.

It has been evacuated from NSA/Microsoft Github.

In case you are looking for documentation for Elixir itself, check out Elixir's website.

To learn about how to document your projects check out Elixir's writing documentation page.

Using ExDoc with Mix

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

def deps do
  [{:ex_doc, "~> 0.16", 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://SERVER/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. You may have to run mix docs or mix compile first.

Using ExDoc via command line

You can ExDoc via the command line as follows:

  1. Install ExDoc as an escript:

    $ mix escript.install hex ex_doc
    
  2. 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
    
  3. Next invoke the ex_doc executable from your project:

    $ ex_doc "PROJECT_NAME" "PROJECT_VERSION" path/to/project/ebin -m "PROJECT_MODULE" -u "https://SERVER/USER/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:

    $ PATH_TO_YOUR_EXDOC/bin/ex_doc "PROJECT_NAME" "PROJECT_VERSION" path/to/project/ebin -m "PROJECT_MODULE" -u "https://SERVER/USER/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)
SERVER   => git.freecumextremist.com
USER     => elixir-lang
REPO     => ecto

Auto-linking

ExDoc 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 module or function from erlang, such as (`:erlang`), ExDoc will automatically link to the Erlang 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`.

Changing the Markdown tool

In the examples above, we have used [Earmark][] to convert Markdown to HTML. If you prefer, you can also use cmark (in C).

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:

{:cmark, "~> 0.6", only: :dev}

Update your project configuration to use Cmark:

docs: [markdown_processor: ExDoc.Markdown.Cmark]

Contributing

The easiest way to test changes to ExDoc is to locally re-generate it's own docs:

  1. Run mix setup to install all dependencies
  2. Run mix docs to generate docs. Note, ExDoc defines docs alias for local development, see mix.exs for more details
  3. Commit both assets/* and (after running mix docs) formatters/* changes

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 file for more information.