C#のサマリコメントをドキュメント化できる「DocFX」使ってみた

0. はじめに

CShaperな人達にとっては、 オリジナルドキュメント作るの面倒くさいので、C#のサマリコメントをドキュメント化したい！ っていうときが3年～5年に1回くらいあるかと思います。そんなときに便利な「DocFX」というのがあるので使ってみました。

1. 環境構築

1-1. DocFXのダウンロード

https://github.com/dotnet/docfx/releases

上記のGitHubサイトからDocFXのzipファイルをダウンロードし、任意のフォルダに解凍します。その後、環境変数にパスを追加しましょう。

1-2. DocFXの初期設定

以下のコマンドを実行し、DocFXの初期フォルダ・ファイルを作成します。

> docfx.exe init -q -o DocFXTest

2. ドキュメント生成の準備

2-1. 生成対象ファイルを用意

ドキュメント生成したいクラス、及びプロジェクトを用意します。今回は以下を使用します。

https://github.com/i-tanaka730/SvnLib/tree/main/SvnLib

2-2. 生成対象ファイルを指定のフォルダに配置

1-2. DocFXの初期設定で生成されたDocFXTest\srcフォルダ配下に、ドキュメント生成したいクラス、及びプロジェクトを配置します。今回の場合は以下のようになります。

DocFXTest
　┗　src
　　┗　SvnLib.csproj
　　┗　SvnService.cs

3. ドキュメントを生成

以下のコマンドを実行します。

DocFXTest> docfx.exe metadata
DocFXTest> docfx.exe build

すると、DocFXTest/_siteフォルダが生成され、これらがドキュメントになります。 (フォルダの中にはhtmlファイルやcssファイルがあります。) なお、DocFXTestフォルダ配下のdocfx.json・index.md・toc.ymlあたりを変更してビルドすることで、ドキュメントのデザインや構成を変更することができます。が、詳細は割愛します。~~というか自分が分かっていなi~~

4. localhostで確認

以下のコマンドで、localhostを立ち上げて確認することができます。

\DocFXTest> docfx.exe serve

キャプチャ.PNG

5. おわりに

サマリコメントをさくっとドキュメント化したい場合はなかなか便利ですね😇
デザインをテンプレート化してしまえばその後も楽ちん😇