docfxをいろいろ調べてみる

Microsoft公式サイトは、docfxをもとに作られています。https://docs.microsoft.com/ja-jp/aspnet/core/tutorials/

またオープンソースでgithubに公開もしています。https://github.com/aspnet/Docs.ja-jp

docfxを使うとMicrosoft公式サイトのように、APIドキュメントと、Markdownで記事を用意できます。docfxの場合は、Markdownの拡張がありプロジェクトのソースコードのリンクなどが簡単にできます。

docfxのインストール

Windowの場合は、chocolateryでインストールするのが簡単。

https://dotnet.github.io/docfx/tutorial/docfx_getting_started.html#2-use-docfx-as-a-command-line-tool

ワークスルー(チュートリアル)

https://dotnet.github.io/docfx/tutorial/walkthrough/walkthrough_overview.html

このワークスルーで、通常のMarkdown記事とAPIドキュメントの作成方法と組み込みサーバーを起動してブラウザで確認する方法がわかります。

ソースコードと画像を追加した記事

 

srcディレクトリーに配置したC#プロジェクトのAPIドキュメントを表示

作業の流れ

上記のサイトを試しに作ってみて一通り作業の流れが分かりました。

最初にdocfx init -qを実行し、必要なディレクトリーを生成します。srcフォルダーが作られるのでここにC#プロジェクトを作ります。docfx.jsonで、metadataのところにsrc/**.csprojと書かれているため配下の*.csファイルがすべてAPIドキュメントの対象になります。

次に、APIドキュメントを作るためdocfx metadaを実行します。C#ソースコードの変更などがあったら作り直す必要があります。

Markdownを書いたらbuildして、serveコマンド後にブラウザーで動作確認です。デフォルトでは、http://localhost:8080/です。

 

コメントを残す

メールアドレスが公開されることはありません。 * が付いている欄は必須項目です

CAPTCHA