Documentation Toolchain Mikan

Mikan とは

Documentation Toolchain Mikan (以下「Mikan」) は、Sphinx で用いられる一部の文法に対応した、reStructuredText ベースのドキュメントツールチェーンです。

ドキュメントの中には、一度作成したら終わりではなく、継続して更新・維持していく必要があるものもあります。一方で、こうしたドキュメントの更新・維持に必要な時間や体制を、常に確保できるとは限りません。

Mikan は、ドキュメントの作成や継続的な更新・維持にかかる負担を減らし、無理なく続けられるドキュメント運用を支えるためのツールです。

なぜ Mikan を開発したのか

時雨堂では、自社製品のドキュメントに Sphinx と reStructuredText を長く利用してきました。一方で、 Sphinx の枠組みの中で自社に必要な機能を実現しようとすると、実装や保守に大きな負担がかかるために、実現を諦めたり運用上の妥協をしたりすることもありました。

そこで、Sphinx の記法をできるだけ引き継ぎながら、自分たちのドキュメント運用に必要な機能を一つのツールチェーンにまとめることにしました。こうして一から開発したのが Mikan です。

Mikan の実例を見る

実際に Mikan で作成されているドキュメントの例として、時雨堂が開発・提供する WebRTC SFU Sora のドキュメントをご覧ください。ページの構成や表示、日本語全文検索などから、Mikan で生成したドキュメントの実際の使い勝手をご確認いただけます。各ページの URL に .md を付けると、Markdown 形式での出力も可能です。

検索専用のサーバーや外部サービスを用意することなく、日本語全文検索を利用できます。 WebAssembly を利用した日本語全文検索エンジンがブラウザ上で動作します。ドキュメントを HTML に出力する際に、検索用のインデックスファイルを自動で生成します。インクリメンタルサーチやタイポ耐性、単語登録、同義語設定、検索品質評価にも対応しています。トークナイザーには Vaporetto を採用しています。

Markdown / llms.txt など LLM が参照しやすい出力

HTML の出力に加えて、.md の拡張子を付けてアクセスすることで、reStructuredText から変換した内容を Markdown 形式で確認できます。
Mikan で生成している Sora ドキュメントでの例： SUPPORT.md 大規模言語モデル (LLM) がドキュメントを参照しやすくするため、llms.txt と llms-full.txt を reStructuredText から Markdown に変換して自動で出力します。
Mikan で生成している Sora ドキュメントでの例： llms.txt / llms-full.txt

Mermaid の SVG 出力

Mermaid 記法の一部に対応しています。 HTML 出力時に SVG として出力するため、ブラウザで表示する際に Mermaid によるレンダリングは必要ありません。現時点では、シーケンス図、状態遷移図、バイナリパケット図に対応しています。また、Mermaid にはない独自記法として、サポートライフサイクル図にも対応しています。

Mikan と Sphinx の比較

Mikan は Sphinx で用いられる一部の文法に対応した、reStructuredText ベースのドキュメントツールチェーンです。 Sphinx との完全互換を目指したものではなく、ドキュメントの作成と継続的な運用に必要な機能を一つのツールチェーンにまとめています。

項目	Mikan	Sphinx
入力形式	reStructuredText	reStructuredText
Sphinx 文法	製品ドキュメントでよく使う directive / role を中心に一部対応	標準 directive / role と拡張機構に対応
設定	`mikan.jsonc`	`conf.py`
拡張機構	なし	Sphinx extension あり
出力形式	HTML / Markdown（`.md` アクセス、`llms.txt` / `llms-full.txt` の自動生成）	HTML / PDF / EPUB など複数ビルダー
フォーマッター	内蔵 (`mikan fmt`)	標準ではなし
リンター	内蔵 (`mikan lint`)	標準ではなし
ローカル開発サーバー	あり (ファイル変更に追従するライブプレビュー)	標準ではなし
日本語全文検索	ブラウザ上で動作する日本語全文検索を標準で提供	標準の全文検索あり (日本語向けの整備は別途必要になる場合がある)
Markdown 出力	あり	標準ではなし
`llms.txt`	自動生成	標準ではなし
Mermaid	ビルド時に SVG 化（対応している図は一部）	拡張で対応
リンク切れチェック	あり	あり
autodoc / intersphinx	非対応	対応
ライセンス	法人・団体向けの有償ソースコードライセンス	BSD-2-Clause

ライセンス

Mikan では、法人・団体向けに有償のソースコードライセンスを提供しています。個人向けのライセンスは、現時点では提供していません。

ライセンス料金：600,000 円（税別）／12 ヶ月

ソースコードライセンス

ソースコードライセンスの契約者には、Mikan のソースコードおよび付随するドキュメントを提供します。 Mikan を自社のドキュメントツールとして利用できるほか、提供されたソースコードを参照、複製、改変して、自社の要件に合わせたドキュメントツールを開発することもできます。

Mikan は、時雨堂が販売しているソフトウェア製品のドキュメントツールとして実際に利用しています。 Mikan のソースコードを活用することで、自社のドキュメントツールを一から開発・保守する場合と比べて、そのためにかかる時間や負担を減らすことが期待できます。

利用方法

Mikan のソースコードをバイナリ形式に変換し、自社のドキュメントツールとして利用する
Mikan のソースコードを参照、複製、改変して自社のドキュメントツールを開発する
Mikan のソースコードの一部を自社のドキュメントツールへ取り込み、必要に応じて改変する

成果物および契約終了時の取り扱い

契約終了後は、Mikan 本体および提供されたソースコード等を利用することはできません。また、ソースコードを参照、複製、改変する権利も終了します。

契約期間中に Mikan のソースコードを参考にして独自に実装した部分は、契約終了後もドキュメントツールで利用できます。一方、Mikan のソースコードそのものを取り込んだ部分は、契約終了後は利用できません。

利用者は、提供された Mikan のソースコード等とその複製を消去する必要があります。

アップデートとサポート

Mikan のソースコード等はアップデートして提供することがあります。

Mikan では原則としてサポートを提供しません。有償サポートを希望される場合は、別途ご相談ください。

よくある質問

Mikan はどのような製品ですか？

Mikan は、reStructuredText (reST) を利用してドキュメントを作成・運用するためのドキュメントツールチェーンです。ドキュメントの作成と、その後の継続的な更新・維持にかかる負担を減らすための機能を備えています。

Mikan は OSS ですか？

いいえ。Mikan は OSS ではありません。現時点では、法人・団体向けの有償のソースコードライセンスを提供しています。利用条件についてはライセンスをご確認ください。

Mikan を利用するにはどうすればいいですか？

現時点では、法人・団体向けの有償のソースコードライセンスのみ提供しています。お見積りのご依頼やお問い合わせは、お問い合わせ先をご確認ください。

Mikan は Sphinx とどのように違いますか？

Mikan は Sphinx で用いられる一部の文法に対応していますが、Sphinx との完全互換を目指したものではありません。フォーマッター、リンター、ローカル開発サーバー、ブラウザ上で動作する日本語全文検索など、ドキュメントの作成から継続的な運用までを支える機能を備えています。項目ごとの違いは Mikan と Sphinx の比較を参照してください。

既存の Sphinx プロジェクトを Mikan に移行できますか？

Mikan は Sphinx で用いられる一部の文法に対応しているため、既存の reST 文書を引き継げる場合があります。ただし、 conf.py や extension を含め、 Sphinx との完全互換には対応していません。引き継げる範囲の概要は Mikan と Sphinx の比較を参照してください。

Mikan は Markdown に対応していますか？

Mikan の入力形式は reStructuredText (reST) です。Markdown を入力してビルドすることには対応していません。一方で、ビルドしたドキュメントを Markdown 形式で出力する機能を備えています。

全文検索を利用するために、専用のサーバーやサービスは必要ですか？

Mikan の日本語全文検索はブラウザ上で動作するため、検索専用のサーバーや外部サービスは必要ありません。

Mikan のサポートはありますか？

原則として、Mikan のサポートは提供していません。有償でのサポートをご希望の場合は、別途ご相談ください。ご契約中のお客様からの改善提案や不具合の報告などのフィードバックは Discord コミュニティで受け付けています。ただし、回答や対応を保証するものではありませんのでご了承ください。

Mikan のソースコードは改変できますか？

自社のドキュメントツールを開発する目的で、ソースコードを参照、複製、改変することができます。詳細は、ご契約前にお渡しする Mikan の使用許諾契約約款をご確認ください。

ライセンス契約の終了後も Mikan を利用できますか？

契約終了後は、Mikan 本体および提供されたソースコード等を利用することはできません。契約期間中に Mikan のソースコードを参考にして独自に実装した部分は、契約終了後もドキュメントツールで利用できます。一方、Mikan のソースコードそのものを取り込んだ部分は、契約終了後は利用できません。詳細は、ご契約前にお渡しする Mikan の使用許諾契約約款をご確認ください。

Mikan で作成したドキュメントは公開できますか？

Mikan で作成したドキュメント自体は公開できます。一方で、Mikan のソースコードを参照、複製、改変して開発したドキュメントツールは、自社のドキュメントを作成・管理する目的でのみ利用できます。不特定多数の第三者に公開したり、利用許諾したりすることはできません。詳細は、ご契約前にお渡しする Mikan の使用許諾契約約款をご確認ください。

お問い合わせ

Mikan に関するご質問・ご相談やお見積りのご依頼は、下記までお送りください。

mikan at shiguredo.jp

送信時は at を @ に置き換えてください。

※ このメールアドレスへの特定電子メールの送信を拒否いたします。

※ お問い合わせの際は、事前によくある質問もご確認ください。