05.Docsプロジェクトの作成

HTMLドキュメント作成用のプロジェクトを作成します。

Visual Studio

ソリューションエクスプローラーの『ソリューション』で右クリック➡『追加(D)』➡『新しいプロジェクト(N)…』でプロジェクトをソリューションに追加します。

新しいプロジェクトを追加

C#の.NETまたは.NET Standardを対象とするクラスライブラリを選択します。

新しいプロジェクトを構成します

プロジェクト名を『Docs』にしています。

『次へ(N)』で次に進みます。

追加情報

『作成(C)』でDocsプロジェクトが作成されます。

Class1.csの削除

自動的に作成された『Class1.cs』を削除します。

DocFXプロジェクトの初期化

Visual Studioのツールバーから『ツール(T)』➡『コマンドライン(L)』➡『開発者用PowerShell(P)』で開発者用PowerShellを起動します。

docfx init -y
Remove-Item docfx.json,index.md,toc.yml

1行目: DocFXの初期ファイルが作成されます。
2行目: ソリューションのルートでは不要なので削除します。

Docsプロジェクトの定義を作成

下記のいずれかの方法でDocsプロジェクトのプロジェクトファイルを開いて編集します。

ソリューションエクスプローラーでプロジェクト名をダブルクリック
ソリューションエクスプローラーでプロジェクト名を右クリック➡プロジェクトファイルの編集

<Project Sdk="Microsoft.NET.Sdk">
  <PropertyGroup>
    <TargetFramework>net10.0</TargetFramework>
    <IsPackable>false</IsPackable>
  </PropertyGroup>
  <Target Name="BuildDocs" AfterTargets="Build"
          Condition="'$(SolutionPath)' != '' And '$(Configuration)' == 'Release'">
    <Message Text="Generating DocFX metadata..."      Importance="high" />
    <WriteLinesToFile File="_includes/version.md" Lines='$(Version)' Overwrite="true" />
    <Message Text="Generating DocFX documentation..." Importance="high" />
    <Exec Command="docfx metadata docfx.json" />
    <Exec Command="docfx build    docfx.json" />
  </Target>
</Project>

3行目～4行目: Docsプロジェクトのプロパティを定義しています。
6行目～7行目: ソリューションのReleaseビルドのときにHTMLドキュメントを生成します。
9行目: mdファイルへの埋め込み用ファイルを生成しています。
11行目～12行目: htmlファイルを生成しています。

DocFXの定義を作成

Docsプロジェクトの直下にDocFXの定義ファイルdocfx.jsonを作成します。

{
  "$schema": "https://raw.githubusercontent.com/dotnet/docfx/main/schemas/docfx.schema.json",
  "metadata": [
    {
      "src": [
        {
          "src": "../",
          "files": [ "/Com/Com.csproj", "/NuGet/NuGet.csproj" ],
          "exclude": [ "**/bin/**", "**/obj/**" ]
        }
      ],
      "dest": "_api",
      "disableGitFeatures": true
    }
  ],
  "build": {
    "content": [
      {
        "files": [ "**/*.md", "toc.yml", "_api/**.yml" ]
        "exclude": [ "_includes/**" ]
      }
    ],
    "dest": "_site",
  }
}

3行目～15行目: apiフォルダーにドキュメント用のymlファイルを生成します。
16行目～24行目: _siteフォルダーにHTMLドキュメントを生成します。
20行目: _includesフォルダーをHTMLドキュメントの生成対象外にしています。

index.mdを作成

_site/index.htmlの生成元となるindex.mdを作成します。

# ProgressLLC.OAuthLib ([!include[](includes/_version.md)])
プログレス合同会社 OAuth 2.0 ライブラリ

## COM版
- <xref:ProgressLLC.OAuthLib.Com>

## NuGet版
- <xref:ProgressLLC.OAuthLib.NuGet>

1行目: includes/_version.mdの内容を取り込んでバージョンを表示します。
5行目: COMのnamespaceをxrefで指定します。
8行目: NuGetのnamespaceをxrefで指定します。

.gitignoreへの追加

DocFXが自動で生成するファイルやフォルダーをGit管理の対象外にします。

   :

# DocFX Genarated file
Docs/_site
Docs/api
Docs/includes

4行目～5行目: DocFXが自動で生成するフォルダーです。
6行目: ビルド時に生成する組み込み用のファイルが格納されるフォルダーです。