ExDoc 配置

快速参考

依赖设置

将 ExDoc 添加到 mix.exs 的 deps 中：

elixir
defp deps do
[
{:ex_doc, ~> 0.34, only: :dev, runtime: false}
]
end

项目配置

在 mix.exs 中配置 project/0 函数：

elixir
def project do
[
app: :weather_station,
version: 0.1.0,
elixir: ~> 1.17,
start_permanent: Mix.env() == :prod,
deps: deps(),

# ExDoc
name: WeatherStation,
sourceurl: https://github.com/acme/weatherstation,
homepageurl: https://acme.github.io/weatherstation,
docs: docs()
]
end

docs/0 函数

定义一个私有的 docs/0 函数以保持项目配置整洁：

elixir
defp docs do
[
main: readme,
logo: priv/static/images/logo.png,
output: doc,
formatters: [html, epub],
source_ref: v#{@version},
extras: extras(),
groupsformodules: groupsformodules(),
groupsforextras: groupsforextras()
]
end

关键选项

设置登录页

main 选项控制用户首先看到的内容：

elixir

使用 README 作为登录页（最常见）

使用特定模块作为登录页

使用自定义指南

该值匹配不含扩展名的额外文件名，或模块名称。

额外内容

额外内容是 API 参考之外的附加页面。将它们添加为文件路径列表：

elixir
defp extras do
[
README.md,
CHANGELOG.md,
LICENSE.md,
guides/getting-started.md,
guides/configuration.md,
guides/deployment.md,
cheatsheets/query-syntax.cheatmd,
notebooks/data-pipeline.livemd
]
end

控制额外内容的标题

默认情况下，ExDoc 使用第一个 h1 标题作为标题。使用关键字元组覆盖：

elixir
defp extras do
[
{README.md, [title: 概述]},
{CHANGELOG.md, [title: 变更日志]},
guides/getting-started.md
]
end

排序

额外内容按列出的顺序显示在侧边栏中。将最重要的页面放在前面：

elixir
defp extras do
[
README.md,
guides/getting-started.md,
guides/architecture.md,
guides/deployment.md,
CHANGELOG.md
]
end

分组

模块分组

将模块组织到侧边栏中的逻辑部分：

elixir
defp groupsformodules do
[
传感器: [
WeatherStation.Sensor,
WeatherStation.Sensor.Temperature,
WeatherStation.Sensor.Humidity,
WeatherStation.Sensor.Pressure
],
数据处理: [
WeatherStation.Pipeline,
WeatherStation.Pipeline.Transform,
WeatherStation.Pipeline.Aggregate
],
存储: [
WeatherStation.Repo,
WeatherStation.Schema.Reading,
WeatherStation.Schema.Station
]
]
end

使用正则表达式按模式分组：

elixir
defp groupsformodules do
[
传感器: [~r/Sensor/],
模式: [~r/Schema/],
管道: [~r/Pipeline/]
]
end

不匹配任何分组的模块将显示在默认的模块标题下。

函数分组

使用 groupsfordocs 在模块内对函数进行分组：

elixir
defp docs do
[
groupsfordocs: [
生命周期: &(&1[:section] == :lifecycle),
查询: &(&1[:section] == :queries),
变更: &(&1[:section] == :mutations)
]
]
end

在模块中使用 @doc 元数据标记函数：

elixir
@doc section: :lifecycle
def startlink(opts), do: GenServer.startlink(MODULE, opts)

@doc section: :queries
def getreading(stationid), do: Repo.get(Reading, station_id)

额外内容分组

在侧边栏中组织指南、速查表和笔记本：

elixir
defp groupsforextras do
[
指南: [
guides/getting-started.md,
guides/configuration.md,
guides/deployment.md
],
速查表: [
cheatsheets/query-syntax.cheatmd,
cheatsheets/ecto-types.cheatmd
],
教程: [
notebooks/data-pipeline.livemd,
notebooks/sensor-setup.livemd
]
]
end

为方便起见使用 glob 模式：

elixir
defp groupsforextras do
[
指南: ~r/guides\/.*/,
速查表: ~r/cheatsheets\/.*/,
教程: ~r/notebooks\/.*/
]
end

依赖文档链接

链接到依赖项的文档，以便 ExDoc 交叉引用能够解析：

elixir
defp docs do
[
deps: [
ecto: https://hexdocs.pm/ecto,
phoenix: https://hexdocs.pm/phoenix,
plug: https://hexdocs.pm/plug
]
]
end

这使得像 t:Ecto.Schema.t/0 这样的引用能够直接链接到依赖文档。

生成文档

bash

生成 HTML 文档

在浏览器中打开

完整的 mix.exs 示例

elixir
defmodule WeatherStation.MixProject do
use Mix.Project

@version 1.3.0
@sourceurl https://github.com/acme/weatherstation

def project do
[
app: :weather_station,
version: @version,
elixir: ~> 1.17,
start_permanent: Mix.env() == :prod,
deps: deps(),
name: WeatherStation,
sourceurl: @sourceurl,
homepageurl: https://acme.github.io/weatherstation,
docs: docs()
]
end

defp docs do
[
main: readme,
logo: priv/static/images/logo.png,
source_ref: v#{@version},
formatters: [html],
extras: extras(),
groupsformodules: groupsformodules(),
groupsforextras: groupsforextras(),
deps: [
ecto: https://hexdocs.pm/ecto,
phoenix: https://hexdocs.pm/phoenix
]
]
end

defp extras do
[
README.md,
CHANGELOG.md,
guides/getting-started.md,
guides/configuration.md,
guides/deployment.md,
cheatsheets/query-syntax.cheatmd,
notebooks/data-pipeline.livemd
]
end

defp groups