ぷろじぇくと、みすじら。

Filtered by Tag: NETFx

DocFX - .NET向けAPIドキュメントを生成するツール

Created at:

誰も触れていなくて紹介しようと思いつつすっかり忘れていたのですがMarkdownGenerator - C#におけるAPI Reference生成のためのドキュメントツールを見て思い出したのでご紹介です。

DocFXとは

DocFXTools for building and publishing API documentation for .NET projectsGitHubのリポジトリの説明がある通り、 主に.NETプロジェクト向けのAPIドキュメント生成ツールで、GitHubの.NET Foundation Organizationの下でMicrosoftが開発しています。

昔であればSandCastleなどがありましたが、モダンなツールらしくメタデータやMarkdownなどからHTMLのサイトを生成します。

DocFXのサンプル

試しに、MraaSharpからMraaSharpのドキュメントを生成してみました。 設定やページは若干適当ですが雰囲気は感じていただけると思います。

DocFXができること

DocFXができることには以下のようなものがあります。

JekyllやHugoなどの静的サイトジェネレーターに近いですが、 そこまで自由なサイトではなく、ドキュメント生成に重きを置いている印象です。

プレビュー中に変更できなかったり、GitHub上のソースコードへ飛べるなどが最初から準備されているのはその辺の考えがあるのではないでしょうか。

DocFXを使って空のサイトを作る

何はともあれDocFXは使ってみるのが一番です。

利用方法はGetting Started with DocFXを見るとコマンドライン、NuGet、ソースからビルド、Visual Studio…といったいろいろな手段があるのですが、 てっとり早く試すのであればコマンドラインがおすすめです。

まずはDocFXのサイトからビルド済みの最新版をダウンロードします。ダウンロード後にアーカイブを展開すると docfx.exe が含まれているのが確認できると思います。

次にコマンドプロンプトを開いて下記のコマンドを実行してプロジェクトを作成します。

docfx init -q -o SampleDoc
Created folder C:\Users\Tomoyo\Downloads\docfx\SampleDoc\src
(略)
Created File C:\Users\Tomoyo\Downloads\docfx\SampleDoc\api\.gitignore
Created config file C:\Users\Tomoyo\Downloads\docfx\SampleDoc\docfx.json
Successfully generated default docfx project to C:\Users\Tomoyo\Downloads\docfx\SampleDoc
Please run:
        docfx "C:\Users\Tomoyo\Downloads\docfx\SampleDoc\docfx.json" --serve
To generate a default docfx website.
Info: Completed executing in 221.5922 milliseconds.

SampleDoc フォルダが作成されてプロジェクトの初期ファイルも生成されます。 -q オプションを外すと設定項目を一つひとつ入力できます。

サイトをビルドする

プロジェクトを作成したらサイトのHTMLを生成してみます。生成するにはSampleDoc フォルダに移動して次のコマンドを実行してください。

..\docfx build

実行すると _site フォルダにHTMLファイルが生成されます。インターネットに公開する場合にはこの _site 以下を何らかの方法でデプロイするとよいでしょう。

サイトを立ち上げてブラウザで表示してみる

ファイルが生成できたら確認のためにプレビューサーバーを起動してみましょう。

..\docfx --serve
Info: Config file docfx.json found, start generating metadata...
Info: No files are found with glob pattern src/**.csproj, excluding **/obj/**,**/bin/**,_site/**, under directory "C:\Users\Tomoyo\Downloads\docfx\SampleDoc"
(略)
Info: [Apply Theme]Theme is applied.
Serving "C:\Users\Tomoyo\Downloads\docfx\SampleDoc\_site" on http://localhost:8080

これで http://localhost:8080/ でサイトが立ち上がります。 ちなみにデフォルトのポート 8080 を利用中の場合には -p オプションを付けて実行することでポートを指定するとよいでしょう。

..\docfx -p 37564 --serve
(略)
Serving "C:\Users\Tomoyo\Downloads\docfx\SampleDoc\_site" on http://localhost:37564

サイトの停止はCtrl+Cです。なお実際はこのコマンドは build も兼ねています。

C#のプロジェクトからソースコードを生成してみる

さて、次はC#のプロジェクトからAPIドキュメントを生成してみます。ドキュメントを生成したいプロジェクトの一式を何か用意しておいてください。

本当はC#のプロジェクトとDocFXのプロジェクトは近い場所に置いておく方がいいと思うのですが、今回は全然違う場所にあるものを指定します。簡単ですので。

docfx.json が設定ファイルとなっているので、このファイルを開いてmetadata の src の場所に "cwd" としてC#のプロジェクトのフォルダパスを指定します(ここでは "C:\Users\Tomoyo\Documents\Work\GitWork\MraaSharp" を指定しています)。

{
  "metadata": [
    {
      "src": [
        {
          "cwd": "C:\\Users\\Tomoyo\\Documents\\Work\\GitWork\\MraaSharp",
          "files": [
            "src/**.csproj"
          ],

そして再度 docfx コマンドでプレビューサーバーを立ち上げると、自動的にC#のコードを解析してXMLドキュメントコメントを読み込み、HTMLを生成します(正確には一旦メタデータファイルを作る)。

プレビューサーバーが立ち上がったのちサイトにアクセスするとナビゲーションに"Api Documentation"が増え、APIのドキュメントにアクセスできます。

Markdownのページを追加してみる

ところでAPIからの生成以外に普通のWebページを追加することもできますので追加してみましょう。ページはMarkdownなどで書けるようになっています。

ページを追加するにはページの内容を書いたMarkdownファイルを作成し、各フォルダ階層に存在する目次ファイルである toc.yml に追記します。

まずはデフォルトで作られる articles フォルダに hello.md ファイルを作成してみましょう。

# Hello!
コンニチハ!

Markdownファイルを作ったら次は toc.yml に追記です。初期状態では intro.md があるのでその後ろに同じようにnameとhrefのセットを足します。

- name: Introduction
  href: intro.md
- name: Hello!
  href: hello.md

そしてまたdotfxコマンドでプレビューサーバーを起動して生成します。生成すると /articles/ 以下に追加したページが並んで表示できるのを確認できるはずです。

終わりに

というわけでDocFXを使うことで簡単に綺麗なドキュメントサイトを生成できるようになります。GitHubにライブラリを公開したけどAPIドキュメントどうしよう…というときにGitHub Pagesとセットで使ったりできます。

まだ少ししか触っていませんが結構細かくカスタマイズできるようになっているので色々調べてみたいところです。

WinDbg/CDBで.loadby sos mscorwksしてSOSデバッガ拡張コマンドを使うとmscorwks.dll/mscordacwks.dllのバージョンが違うと怒られる

Created at:

Windows Server 2003 環境の.NET FrameworkとWindows Vista SP2の.NET Frameworkは微妙にバージョンが違ったりします(W2k3は最新で2.0.50727.4016、Vistaは2.0.50727.3053)。

そんな感じで手元とは異なった環境で取ったメモリダンプファイルを開いて、SOSデバッガ拡張でのぞき見ようとすると次のようにエラーになったりします。

0:023> .loadby sos mscorwks
0:023> !DumpHeap
*********************************************************************
* Symbols can not be loaded because symbol path is not initialized. *
*                                                                   *
* The Symbol Path can be set by:                                    *
*   using the _NT_SYMBOL_PATH environment variable.                 *
*   using the -y  argument when starting the debugger. *
*   using .sympath and .sympath+                                    *
*********************************************************************
PDB symbol for mscorwks.dll not loaded
Failed to load data access DLL, 0x80004005
Verify that 1) you have a recent build of the debugger (6.2.14 or newer)
            2) the file mscordacwks.dll that matches your version of mscorwks.dll is 
                in the version directory
            3) or, if you are debugging a dump file, verify that the file 
                mscordacwks___.dll is on your symbol path.
            4) you are debugging on the same architecture as the dump file.
                For example, an IA64 dump file must be debugged on an IA64
                machine.

You can also run the debugger command .cordll to control the debugger's
load of mscordacwks.dll.  .cordll -ve -u -l will do a verbose reload.
If that succeeds, the SOS command should work on retry.

If you are debugging a minidump, you need to make sure that your executable
path is pointing to mscorwks.dll as well.
0:023> .cordll
CLR DLL status: ERROR: Unable to load DLL mscordacwks_x86_x86_2.0.50727.3053.dll, Win32 error 0n2
0:023> .load C:\Windows\Microsoft.NET\Framework\v2.0.50727\mscorwks.dll
0:023> .cordll -ve -u -l
CLR DLL status: No load attempts
0:023> !DumpHeap
CLRDLL: C:\WINDOWS\Microsoft.NET\Framework\v2.0.50727\mscordacwks.dll:2.0.50727.4016 f:0
doesn't match desired version 2.0.50727.3053 f:0
CLRDLL: Unable to find mscordacwks_x86_x86_2.0.50727.3053.dll by mscorwks search
CLRDLL: Unable to find 'mscordacwks_x86_x86_2.0.50727.3053.dll' on the path
CLRDLL: Unable to find mscorwks.dll by search
CLRDLL: ERROR: Unable to load DLL mscordacwks_x86_x86_2.0.50727.3053.dll, Win32 error 0n2
Failed to load data access DLL, 0x80004005
Verify that 1) you have a recent build of the debugger (6.2.14 or newer)
            2) the file mscordacwks.dll that matches your version of mscorwks.dll is 
                in the version directory
            3) or, if you are debugging a dump file, verify that the file 
                mscordacwks_<arch>_<arch>_<version>.dll is on your symbol path.
            4) you are debugging on the same architecture as the dump file.
                For example, an IA64 dump file must be debugged on an IA64
                machine.

You can also run the debugger command .cordll to control the debugger's
load of mscordacwks.dll.  .cordll -ve -u -l will do a verbose reload.
If that succeeds, the SOS command should work on retry.

If you are debugging a minidump, you need to make sure that your executable
path is pointing to mscorwks.dll as well.

そんなときは対応するDLLを取得できるようにシンボルパスを設定してあげます。

WinDbg の File → Symbol File Path ... で Symbol path: に

symsrv*symsrv.dll*c:\localcache*http://msdl.microsoft.com/download/symbols

Reload チェックボックスをオンでOKで閉じます。

もしすでに .loadby sos mscorwks を実行して怒られたあとなら、一度次のコマンドで再読み込みできるようにします。

.cordll -ve -u -l

あとは普通にデバッガ拡張コマンドが使えるようになってるはずです。