カスタムドキュメントパイプラインの統合

この記事は、「API Extractorの実行」ページからのチュートリアルの続きです。そちらから始めることをお勧めします。

前のページはこちらで、**api-documenter**ツールによって作成された出力をレンダリングできる様々なドキュメントシステムについて説明しました。しかし、カスタムレイアウトが必要な場合、または全く異なるシステムと統合したい場合はどうでしょうか？コードを書くことを恐れないのであれば、API Extractorを使用すると比較的簡単に実現できます。

api-documenterプロジェクトのフォーク

**api-documenter**プロジェクトはコードサンプルとして設計されているため、小さな変更を加えたい場合は、単にフォークしてコードを変更できます。確認する必要がある基本的なファイルは次のとおりです。

• apps/api-documenter - GitHub上のメインプロジェクトフォルダ。

• MarkdownAction.ts - このソースファイルは、api-documenter markdownコマンドラインとそのパラメータを定義しています。ApiModelオブジェクトを読み込み、MarkdownDocumenterに渡します。

• MarkdownDocumenter.ts - これは、調査する必要がある主なドキュメントジェネレータです。TypeScriptコンストラクトのツリーをトラバースし、各コンストラクトをレンダリングする方法を示しています。TSDocライブラリは既にリッチテキスト要素のツリーを表すための優れたAPIを提供しているため、MarkdownDocumenterクラスは、ウェブサイト上の各ページを表す巨大なTSDoc「コメント」を生成するというアプローチを取っています。これは珍しいアプローチですが、TSDoc入力からTSDoc出力を生成することで、すべての内部コンテンツを変換する必要がなくなります。

• api-documenter/src/nodes - このフォルダは、完全なウェブページを作成するために必要な見出し、テーブル、ノートボックスなどのカスタムノードタイプでTSDocライブラリを拡張しています。

• MarkdownEmitter.ts - このクラスは、TSDoc「コメント」（およびカスタムノード）からMarkdownドキュメントを生成する最終段階です。この分離により、将来のモジュール化が可能になります。たとえば、異なるMarkdownフレーバーをサポートしたい場合、MarkdownDocumenterクラスはそのことを気にする必要がありません。理論的には、同じ中間TSDocノードツリーからHTMLなどの全く異なる出力形式を出力することもできます。

独自のジェネレータのコーディング

上記のコンポーネントを見ると、このコードの大部分はドキュメントコンテンツの表示に関するものです。すべてのAPI宣言を訪問し、その様々な属性をレンダリングするメインループは、MarkdownDocumenter.tsに完全に含まれており、比較的コンパクトです。

これは@microsoft/api-extractor-modelライブラリのおかげで可能です。このライブラリは、.api.jsonファイルのフォルダを読み込み、その内容を解析し、クエリできる優れた階層を提供するという難しい作業を行います。このライブラリはまた、@linkハイパーリンクなどの宣言参照を解決するために使用できるApiModel.resolveDeclarationReference()関数を実装しています。

**@microsoft/api-extractor-model**のREADME.mdでは、基本的な階層とそのトラバース方法、ApiClass、ApiEnum、ApiInterfaceなどの個々のクラスについて、かなり詳細なコードコメントが説明されています。

完全に明らかではない側面の1つは、TSDocをMarkdown以外の形式にレンダリングする方法です。Reactを使用したHTMLのレンダリングの例として、DocHtmlView.tsxも参照できます。これはTSDoc Playgroundの「HTML」タブをレンダリングします。

行き詰まった場合や質問がある場合は、API Extractor開発者は通常、**rushstack**モノレポのZulipチャットルームから連絡できます。

そして、API Extractorが優れたオープンソースドキュメントエンジンと連携できるようにするアダプタを実装した場合…教えてください！これらのドキュメントで必ず言及します！ :-)