在线时间:8:00-16:00
迪恩网络APP
随时随地掌握行业动态
扫描二维码
关注迪恩网络微信公众号
开源软件名称:elixir-lang/ex_doc开源软件地址:https://github.com/elixir-lang/ex_doc开源编程语言:Elixir 65.1%开源软件介绍:ExDocExDoc 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. FeaturesExDoc ships with many features:
UsageYou can use ExDoc with Mix (recommended for Elixir projects), with Rebar (recommended for Erlang projects), or via the command line. Using ExDoc with MixFirst add ExDoc as a dependency. ExDoc requires Elixir v1.10 or later: def deps do
[
{:ex_doc, "~> 0.27", only: :dev, runtime: false},
]
end Then run
ExDoc will automatically pull in information from your projects, like the application and version. However, you may want to set 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 Using ExDoc with Rebar3From Erlang/OTP 24+, you can use ExDoc to render your Erlang documentation written with EDoc. See Using ExDoc via command lineYou can ExDoc via the command line as follows:
For example, here are some acceptable values:
Syntax highlightingExDoc uses the makeup project for syntax highlighting. By default, it includes highlighters for Erlang and Elixir. To highlight other languages, simply add the equivalent {:makeup_html, ">= 0.0.0", only: :dev, runtime: false} You can find all support languages under the Makeup organization on GitHub. MetadataExDoc supports certain metadata keys in your documentation. For example, the @moduledoc since: "1.10.0"
@doc since: "1.13.1" In Erlang's EDoc, you would do: %% @since 0.1.0 The following metadata is available for both modules and functions:
The following metadata is available for modules:
Auto-linkingExDoc for Elixir will automatically generate links across modules and functions if you enclose them in backticks:
ExDoc supports linking to modules ( You can also use a custom text, e.g.: Link to extra pages like this: Admonition blocksYou 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. The syntax is as follows:
The result for the previous syntax is as follows:
For example, if you change the class name to
ExtensionsExDoc 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 MathIf you write TeX-style math in your Markdown (like <link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/[email protected]/dist/katex.min.css" integrity="sha384-beuqjL2bw+6DBM2eOpr5+Xlw+jiH44vMdVQwKxV28xxpoInPHTVmSvvvoPq9RdSh" crossorigin="anonymous">
<script defer src="https://cdn.jsdelivr.net/npm/[email protected]/dist/katex.min.js" integrity="sha384-aaNb715UK1HuP4rjZxyzph+dVss/5Nx3mLImBe9b0EW4vMUkc1Guw4VRyQKBC0eG" crossorigin="anonymous"></script>
<script defer src="https://cdn.jsdelivr.net/npm/[email protected]/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 plotsOther objects you may want to render in a special manner are code snippets. For example, assuming your Markdown includes Vega-Lite specification in <script src="https://cdn.jsdelivr.net/npm/[email protected]"></script>
<script src="https://cdn.jsdelivr.net/npm/[email protected]"></script>
<script src="https://cdn.jsdelivr.net/npm/[email protected]"></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 vega/vega-embed. Rendering Mermaid graphsSimilarly to the example above, if your Markdown includes Mermaid graph specification in <script src="https://cdn.jsdelivr.net/npm/[email protected]/dist/mermaid.min.js"></script>
<script>
document.addEventListener("DOMContentLoaded", function () {
mermaid.initialize({ startOnLoad: false });
let id = 0;
for (const codeEl of document.querySelectorAll("pre code.mermaid")) {
const preEl = codeEl.parentElement;
const graphDefinition = codeEl.textContent;
const graphEl = document.createElement("div");
const graphId = "mermaid-graph-" + id++;
mermaid.render(graphId, graphDefinition, function (svgSource, bindListeners) {
graphEl.innerHTML = svgSource;
bindListeners && bindListeners(graphEl);
preEl.insertAdjacentElement("afterend", graphEl);
preEl.remove();
});
}
});
</script> For more details and configuration options see the Mermaid usage docs. ContributingThe easiest way to test changes to ExDoc is to locally rebuild the app and its own documentation:
Note that Node 17 or later is not supported due to API breaking changes with Webpack. LicenseExDoc 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. |
2023-10-27
2022-08-15
2022-08-17
2022-09-23
2022-08-13
请发表评论