【Unity】DocFXを用いてプロジェクトのドキュメントを自動生成する

はじめに

今回はDocFXというドキュメント生成ツールを使い、Unityプロジェクトのドキュメントを作っちゃおうという記事になります。

dotnet.github.io

f:id:hanaaaaaachiru:20211223222426p:plain — 自動生成したドキュメント

はじめに
DocFXをインストールする
出力先のフォルダを作成する
ドキュメント化する
さいごに

DocFXをインストールする

DocFXにはインストール方法がたくさんあるようですが、私はHomebrewを使ってインストールしていきたいと思います。

Chocolatey: choco install docfx -y.

Homebrew (owned by community): brew install docfx.

GitHub: download and unzip docfx.zip from https://github.com/dotnet/docfx/releases, extract it to a local folder, and add it to PATH so you can run it anywhere.

NuGet: nuget install docfx.console. docfx.exe is under folder docfx.console/tools/.

Getting Started with DocFX | DocFX website

以下のコマンドをターミナルに打ち込んでいきます。

$ brew install docfx

出力先のフォルダを作成する

作業フォルダを作成したい場所に移動(今回はGitHub Actionsを使ったりせず、純粋にドキュメントをお試しで作成しようという方針なのでDesktop等の好きな場所で大丈夫です)し、以下のコマンドを打ち込みます。

$ docfx init -q -o <ディレクトリ名>

docfx init helps generate an docfx.json file.

docfx.exe User Manual | DocFX website

すると以下のようなファイル群が構成されます。

<ディレクトリ名> 
　　|-- api
　　|　　|-- index.md
　　|　　|-- toc.yml
　　|-- apidoc
　　|-- articles
　　|　　|-- intro.md
　　|　　|-- toc.yml
　　|-- docfx.json
　　|-- images
　　|-- index.md
　　|-- src
　　|-- toc.yml

また初期のdocfx.jsonは以下のような内容になります。

{
  "metadata": [
    {
      "src": [
        {
          "files": [
            "src/**.csproj"
          ]
        }
      ],
      "dest": "api",
      "disableGitFeatures": false,
      "disableDefaultFilter": false
    }
  ],
  "build": {
    "content": [
      {
        "files": [
          "api/**.yml",
          "api/index.md"
        ]
      },
      {
        "files": [
          "articles/**.md",
          "articles/**/toc.yml",
          "toc.yml",
          "*.md"
        ]
      }
    ],
    "resource": [
      {
        "files": [
          "images/**"
        ]
      }
    ],
    "overwrite": [
      {
        "files": [
          "apidoc/**.md"
        ],
        "exclude": [
          "obj/**",
          "_site/**"
        ]
      }
    ],
    "dest": "_site",
    "globalMetadataFiles": [],
    "fileMetadataFiles": [],
    "template": [
      "default"
    ],
    "postProcessors": [],
    "markdownEngineName": "markdig",
    "noLangKeyword": false,
    "keepFileLink": false,
    "cleanupCacheHistory": false,
    "disableGitFeatures": false
  }
}