exdoc-config

ExDoc 配置

快速参考

主题	参考
Markdown、速查表（.cheatmd）、Livebook（.livemd）	references/extras-formats.md
自定义 head/body 标签、语法高亮、嵌套、注释	references/advanced-config.md

检查关卡

在确认 ExDoc 已正确接入或文档已构建之前，请按以下顺序检查：

1. 依赖已解析 — 在项目根目录运行 mix deps.get。**通过条件：**退出代码为 0，且 mix.exs 中包含 ex_doc，如依赖设置所示（或包含项目中等效的、仅用于开发环境的文档依赖）。
2. 额外页面路径有效 — 对于 extras/0 中的每个路径字符串（以及使用时的 groups_for_extras/0），确认该路径在仓库中存在，或你刚刚创建了该文件。**通过条件：**运行 mix docs 时不存在过时或拼写错误的路径。
3. 文档构建成功 — 运行 mix docs。**通过条件：**退出代码为 0，且 HTML 入口文件存在于 <output>/index.html（默认为 <project>/doc/index.html；如果更改了 output，请使用 docs: [output: ...]）。

对于速查表、Livebook 或自定义 head/body 资源，请遵循同样的“列出前确认路径存在”规则；请参阅何时加载参考资料。

依赖设置

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

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

项目配置

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

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

    # ExDoc
    name: "WeatherStation",
    source_url: "https://github.com/acme/weather_station",
    homepage_url: "https://acme.github.io/weather_station",
    docs: docs()
  ]
end

docs/0 函数

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

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

关键选项

选项	默认值	说明
main	"api-reference"	首页模块名称或额外文件名（不含扩展名）
logo	nil	侧边栏中显示的徽标图片路径
output	"doc"	生成文档的输出目录
formatters	["html"]	输出格式列表（"html"、"epub"）
source_ref	"main"	用于“查看源代码”链接的 Git ref
assets	nil	静态资源的源目录到目标目录的映射
deps	[]	依赖项文档链接

设置首页

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

# Use the README as the landing page (most common)
docs: [main: "readme"]

# Use a specific module as the landing page
docs: [main: "WeatherStation"]

# Use a custom guide
docs: [main: "getting-started"]

该值对应不带扩展名的额外文件名，或模块名称。

额外页面

额外页面是 API 参考之外的其他页面。将文件路径列表添加到配置中：

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 标题作为页面标题。使用关键字元组覆盖：

defp extras do
  [
    {"README.md", [title: "Overview"]},
    {"CHANGELOG.md", [title: "Changelog"]},
    "guides/getting-started.md"
  ]
end

排序

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

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

分组

模块分组

在侧边栏中将模块整理到逻辑分区：

defp groups_for_modules do
  [
    "Sensors": [
      WeatherStation.Sensor,
      WeatherStation.Sensor.Temperature,
      WeatherStation.Sensor.Humidity,
      WeatherStation.Sensor.Pressure
    ],
    "Data Processing": [
      WeatherStation.Pipeline,
      WeatherStation.Pipeline.Transform,
      WeatherStation.Pipeline.Aggregate
    ],
    "Storage": [
      WeatherStation.Repo,
      WeatherStation.Schema.Reading,
      WeatherStation.Schema.Station
    ]
  ]
end

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

defp groups_for_modules do
  [
    "Sensors": [~r/Sensor/],
    "Schemas": [~r/Schema/],
    "Pipeline": [~r/Pipeline/]
  ]
end

不匹配任何分组的模块会显示在默认的“Modules”标题下。

函数分组

使用 groups_for_docs 对模块中的函数分组：

defp docs do
  [
    groups_for_docs: [
      "Lifecycle": &(&1[:section] == :lifecycle),
      "Queries": &(&1[:section] == :queries),
      "Mutations": &(&1[:section] == :mutations)
    ]
  ]
end

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

@doc section: :lifecycle
def start_link(opts), do: GenServer.start_link(__MODULE__, opts)

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

额外页面分组

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

defp groups_for_extras do
  [
    "Guides": [
      "guides/getting-started.md",
      "guides/configuration.md",
      "guides/deployment.md"
    ],
    "Cheatsheets": [
      "cheatsheets/query-syntax.cheatmd",
      "cheatsheets/ecto-types.cheatmd"
    ],
    "Tutorials": [
      "notebooks/data-pipeline.livemd",
      "notebooks/sensor-setup.livemd"
    ]
  ]
end

也可以使用 glob 模式简化配置：

defp groups_for_extras do
  [
    "Guides": ~r/guides\/.*/,
    "Cheatsheets": ~r/cheatsheets\/.*/,
    "Tutorials": ~r/notebooks\/.*/
  ]
end

依赖文档链接

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

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 这样的引用就能直接链接到依赖项文档。

生成文档

# Generate HTML docs
mix docs

# Open in browser
open doc/index.html

完整的 mix.exs 示例

defmodule WeatherStation.MixProject do
  use Mix.Project

  @version "1.3.0"
  @source_url "https://github.com/acme/weather_station"

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

  defp docs do
    [
      main: "readme",
      logo: "priv/static/images/logo.png",
      source_ref: "v#{@version}",
      formatters: ["html"],
      extras: extras(),
      groups_for_modules: groups_for_modules(),
      groups_for_extras: groups_for_extras(),
      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_for_modules do
    [
      "Sensors": [~r/Sensor/],
      "Data Processing": [~r/Pipeline/],
      "Storage": [~r/Schema|Repo/]
    ]
  end

  defp groups_for_extras do
    [
      "Guides": ~r/guides\/.*/,
      "Cheatsheets": ~r/cheatsheets\/.*/,
      "Tutorials": ~r/notebooks\/.*/
    ]
  end

  defp deps do
    [
      {:phoenix, "~> 1.7"},
      {:ecto_sql, "~> 3.12"},
      {:ex_doc, "~> 0.34", only: :dev, runtime: false}
    ]
  end
end

何时加载参考资料

• 将速查表或 Livebook 设置为额外页面 -> extras-formats.md
• 注入自定义 CSS/JS、配置语法高亮或调整模块嵌套 -> advanced-config.md