exdoc-config

ExDoc の設定

クイックリファレンス

トピック	リファレンス
Markdown、チートシート（.cheatmd）、ライブブック（.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: ...] を使用します）。

チートシート、ライブブック、またはカスタムの head/body アセットについても、同じ「一覧に追加する前にパスの存在を確認する」ルールに従ってください。リファレンスを読み込むタイミング を参照してください。

依存関係の設定

mix.exs の deps に ExDoc を追加します。

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

便宜上、グロブパターンを使用できます。

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

リファレンスを読み込むタイミング

• チートシートやライブブックを追加ページとして設定する場合 -> extras-formats.md
• カスタム CSS/JS の挿入、構文ハイライトの設定、またはモジュールのネストの調整を行う場合 -> advanced-config.md