BloGroonga

2023-01-24

グルカイ!第25回「ドキュメントのビルドシステムについて」を開催しました!

グルカイ!第25回「ドキュメントのビルドシステムについて」の内容をまとめました!

今回は、Groongaのドキュメントのビルドシステムについて解説いただきました! 解説時に使用した図はこちらです。

Groongaのドキュメントのビルドシステムについては、以下のクリアコードのブログ(ククログ)にもまとめられています。

Sphinx

SphinxはPython製のドキュメントビルダーです。 reStructuredText( .rst )形式のファイルを入力に、HTMLやPDFなどを出力できます。 Groongaでは .rst 形式のファイルからHTMLを出力しています。

Sphinxの国際化機能

Groongaは英語と日本語のドキュメントをサポートしています。 日本語をサポートしているのは、ユーザーに日本人が多いためです。

Sphinxには国際化機能があり、 .rst ファイルと翻訳情報を使って各言語のHTMLを作成することができます。 Groongaでは以下のように英語の .rst ファイルと、英語から日本語の翻訳情報を使って日本語のHTMLを作成しています。

英語の.rstファイル + 翻訳済みテキスト -> Sphinx -> 日本語HTML

ここで、翻訳済みテキストは、Potable Object(.po)という形式で、GNU gettextが作ったフォーマットを使っています。

Sphinxの国際化機能でできること、できないこと

Sphinxの国際化機能では以下のことができます。

  • 英語の.rstファイルから、翻訳対象のテキストを自動で抽出
  • 英語の.rstファイルと翻訳済みテキストから、翻訳済みドキュメントを生成

一方、Sphinxの国際化機能では以下のことができません。

  • 翻訳済みテキストの管理
    • マージ
    • 英語の.rstの更新を検知 -> 翻訳対象を抽出 -> マージ という一連の作業

翻訳済みテキストは前述の通りGNU gettextのPortable Object(.po)形式なので、GNU gettext関連ツールで管理することができます。 具体的には、GNU gettext関連ツールでは、マージをすることができます。マージとは具体的には以下の作業を指します。

  1. 翻訳対象を抽出
  2. 抽出したものを翻訳
  3. 翻訳対象を追加
  4. 3.の対象を抽出
  5. 2.と4.を混ぜる(マージ)

しかし、英語の.rstの更新を検知 -> 翻訳対象の抽出 -> マージはGNU gettext関連ツールでもできません。

Groongaのドキュメントのビルドシステムが行っていること

ドキュメント関係のビルドシステムでは上述のSphinxの国際化機能でもGNU gettextでもできない、 英語の.rstの更新を検知 -> 翻訳対象の抽出 -> マージ を実現しています。

具体的な実現方法は次回以降解説します。

Groongaのビルドシステムについて

現在Groongaのビルドシステムでは、GNU AutotoolsとCMakeを使用していますが、今後はCMakeに一本化していく予定です。 GroongaはWindowsもサポートしているので、Windows上でも動作するCMakeの方が嬉しいといった理由からです。 GNU AutotoolsはshベースなためWindowsでは動きません。

現在はリリースやドキュメントまわりがGNU Autotoolsでしか動きませんが、これらも随時CMakeに移行していく予定です。