Packages
ex_doc
0.13.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
lib/ex_doc/cli.ex
defmodule ExDoc.CLI do
@moduledoc """
Command line parser for ExDoc
"""
@doc """
Handle the command line parsing and trigger all the required mechanism to
transform the MarkDown documents into a specified format (default: HTML)
"""
def run(args, generator \\ &ExDoc.generate_docs/3) do
{opts, args, _} = OptionParser.parse(args,
aliases: [o: :output, f: :formatter, c: :config, r: :source_root,
u: :source_url, m: :main, p: :homepage_url, l: :logo,
e: :extra, v: :version, a: :canonical],
switches: [extra: :keep])
cond do
List.keymember?(opts, :version, 0) ->
do_version()
true ->
do_generate(args, opts, generator)
end
end
defp do_version do
IO.puts "ExDoc v#{ExDoc.version}"
end
defp do_generate(args, opts, generator) do
[project, version, source_beam] = parse_args(args)
Code.prepend_path(source_beam)
opts =
opts
|> Keyword.put(:source_beam, source_beam)
|> merge_config()
generator.(project, version, opts)
end
defp merge_config(opts) do
opts
|> formatter_options()
|> extra_files_options()
end
defp formatter_options(opts) do
case Keyword.fetch(opts, :config) do
{:ok, config} ->
opts
|> Keyword.delete(:config)
|> Keyword.put(:formatter_opts, read_config(config))
_ -> opts
end
end
defp extra_files_options(opts) do
extras = Keyword.get_values(opts, :extra)
opts
|> Keyword.delete(:extra)
|> Keyword.put(:extras, extras)
end
defp read_config(path) do
config = File.read!(path)
{result, _} = Code.eval_string(config)
unless is_list(result) do
raise "expected a keyword list from config file: #{inspect path}"
end
result
end
defp parse_args([_project, _version, _source_beam] = args), do: args
defp parse_args([_, _, _ | _]) do
IO.puts "Too many arguments.\n"
print_usage()
exit {:shutdown, 1}
end
defp parse_args(_) do
IO.puts "Too few arguments.\n"
print_usage()
exit {:shutdown, 1}
end
defp print_usage do
IO.puts ~S"""
Usage:
ex_doc PROJECT VERSION BEAMS [OPTIONS]
Examples:
ex_doc "Ecto" "0.8.0" "_build/dev/lib/ecto/ebin" -u "https://github.com/elixir-lang/ecto"
ex_doc "Project" "1.0.0" "_build/dev/lib/project/ebin" -e "docs/extra_page.md"
Options:
PROJECT Project name
VERSION Version number
BEAMS Path to compiled beam files
-c, --config Give configuration through a file instead of command line
-o, --output Path to output docs, default: "doc"
-f, --formatter Docs formatter to use, default: "html"
-a, --canonical Indicate the preferred URL with rel="canonical" link element, default: nil
-r, --source-root Path to the source code root, default: "."
-u, --source-url URL to the source code
--source-ref Branch/commit/tag used for source link inference, default: "master"
-m, --main The main, entry-point module in docs,
default: "api-reference" when --formatter is "html"
-p, --homepage-url URL to link to for the site name
--extra-section Allow user to define the title for the additional Markdown files,
default: "PAGES"
-e, --extra Allow users to include additional Markdown files
May be given multiple times
-l, --logo Path to the image logo of the project (only PNG or JPEG accepted)
The image size will be 64x64 when --formatter is "html"
default: `nil`
-v, --version Print ExDoc version
## Source linking
ExDoc by default provide links to the source code implementation as
long as `--source-url` or `--source-url-pattern` is provided. If you
provide `--source-url`, ExDoc will inflect the url pattern automatically
for GitHub and Bitbucket URLs. For example:
--source-url "https://github.com/elixir-lang/ecto"
Will be inflected as:
https://github.com/elixir-lang/ecto/blob/master/%{path}#L%{line}
To specify a particular branch or commit, use the `--source-ref` option:
--source-url "https://github.com/elixir-lang/ecto" --source-ref "v1.0"
will result in the following URL pattern:
https://github.com/elixir-lang/ecto/blob/v1.0/%{path}#L%{line}
"""
end
end