12.2.1. 導入#

このドキュメントは、Groongaドキュメントの執筆、生成、管理の手順について説明します。以下の手順で、Groongaドキュメントの向上や更新に貢献できます。

12.2.1.1. Groongaリポジトリをフォークしクローンする方法#

Groongaドキュメントへ貢献するには、まずはGroongaリポジトリをフォークしクローンするとこから始めます。そうすることで、あなたのリポジトリで個人的な変更や実験が可能になります。他にも、その成果をGroongaリポジトリにあなたの貢献として送ることもできます。まずは、次の手順に倣って、フォークとクローンをしてください。

  1. GitHubの groonga/groonga へ移動してください。

  2. Fork ボタンをクリックして、Groongaリポジトリをフォークしてください。

  3. 下記のコマンドでフォークしたGroongaリポジトリをクローンしてください。

% git clone --recursive git@github.com:${YOUR_GITHUB_ACCOUNT}/groonga.git

12.2.1.2. 必要なソフトウェアのインストール#

Groongaはドキュメントツールとして Sphinx を使います。

以下はSphinxをインストールするコマンドラインです。

Debian GNU/Linux, Ubuntu:

% ./setup.sh
% sudo pip install -r doc/requirements.txt
% (cd doc && bundle install)

AlmaLinux, Fedora:

% sudo dnf install -y python-pip gettext
% sudo pip install -r doc/requirements.txt
% (cd doc && bundle install)

macOS:

% brew bundle
% export PATH=$(brew --prefix gettext)/bin:$PATH
% pip install -r doc/requirements.txt
% (cd doc && bundle install)

12.2.1.3. cmake を --preset=doc 付きで実行#

Groonga は、デフォルトではドキュメントの生成を無効化しています。 cmake に --preset=doc オプションを追加して明示的に有効にする必要があります。:

% cmake -S . -B ../groonga.doc --preset=doc

これで、 Groonga ドキュメントをビルドする準備が出来ました。

12.2.1.4. HTMLファイルを生成#

以下のコマンドでHTMLファイルを生成できます。:

% cmake --build ../groonga.doc

生成されたHTMLドキュメントは ../groonga.doc/doc/ja/html/ にあります。

12.2.1.5. ドキュメントを編集する方法#

Groongaドキュメントは、reStructuredText (.rst) または Markdown (.md) で書かれています。Groongaドキュメントのファイルは、doc/source 配下にあります。それぞれのページに対応した .rst ファイルまたは、 .md が必ず１つあります。対応するファイルを変更することで、対象のドキュメントを編集できます。例えば、この 導入 ページを編集したい場合は、doc/source/contribution/documentation/introduction.rst ファイルを編集すればよいです。編集したいファイルをみつけて、編集してください。

12.2.1.6. 新しいドキュメントを追加する方法#

新しいドキュメントを追加したい場合は、以下のコマンドで新しいドキュメントを doc/files.amと doc/files.cmake に追加する必要があります。

$ cmake -S . -B ../groonga.doc --preset=doc
$ cmake --build ../groonga.doc
$ ninja doc_update_files -C ../groonga.doc

このケースでは、新しいドキュメントだけでなく、 doc/files.am と doc/files.cmake もコミットする必要があることに注意してください。

12.2.1.7. HTMLファイルで変更を確認する#

HTML形式でドキュメントの変更をブラウザで確認できます。次の２つの手順に倣ってください。

  1. 変更を反映したHTMLファイルを生成する

  2. Webブラウザで生成されたHTMLファイルを確認する

12.2.1.7.1. 変更を反映したHTMLファイルを生成する#

次のコマンドで、変更を反映したHTMLファイルを生成します。生成されたファイルは、../groonga.doc/doc/en/html/ 配下にあります。各 .rst または .md ファイルに対応するファイルが生成されています。

% cmake --build ../groonga.doc

12.2.1.7.2. Webブラウザで生成されたHTMLファイルを確認する#

生成されたファイルをWebブラウザで開き、変更を確認できます。例えば、この 導入 ページを編集した場合、次のコマンドで変更を確認できます。

% open ../groonga.doc/doc/en/html/contribution/documentation/introduction.html

12.2.1.8. パッチを送る#

GitHub上のGroongaリポジトリに対してプルリクエストを通じてパッチを送ることができます。次の手順で、気軽にプルリクエストを作ってみましょう。

  • プルリクエストの準備をする

  • プルリクエストを送る

12.2.1.8.1. プルリクエストの準備をする#

次のコマンドで、変更をコミットし、その変更をGitHubにある自分のフォークリポジトリにプッシュします。

% git switch -c your-working-branch
% git add doc
% git commit -m 'Describe your works here'
% git push origin your-working-branch

12.2.1.8.2. プルリクエストを送る#

これで、アップストリームのGroongaリポジトリにプルリクエストを送る準備ができました。次のステップに従い実際にプルリクエストを送ってみましょう。

  1. GitHubで自分のフォークリポジトリにアクセスします

  2. Compare & pull requestボタンをクリックします

  3. 変更がすべて反映されているかを確認します

  4. Create Pull Requestボタンをクリックして、プルリクエストを送ります

12.2.1.9. 任意: ドキュメントを翻訳する#

任意のステップになります。

Groongaドキュメントの編集とプレビューが完了したら、次のステップは、ドキュメントの翻訳になります。翻訳をすることで、Groongaコミュニティのより広い範囲のユーザーがGroongaを利用しやすくなります。英語以外の言語に翻訳することで、非英語話者でもGroongaのドキュメントを理解しやすくなります。次の手順で、Groongaドキュメントを翻訳しましょう。

  1. .edit.po ファイル内のドキュメントを翻訳する

  2. 翻訳を .po ファイルに反映する

  3. HTMLファイルで翻訳を確認する

12.2.1.9.1. .edit.po ファイル内のドキュメントを翻訳する#

次のコマンドで、翻訳用である .edit.po ファイルを生成します。生成されたファイルは ../groonga.doc/doc/locale/${LANGUAGE}/LC_MESSAGES 配下にあります。各 .rst または .md ファイルに対応するファイルが生成されています。対応する .edit.po ファイルに翻訳を追加します。

% cmake --build ../groonga.doc

例えば、この 導入 ページを編集して、日本語訳を追加したい場合は、../groonga.doc/doc/ja/LC_MESSAGES/contribution/documentation/introduction.edit.po ファイルを更新します。

注意

.edit.po ファイルに翻訳を追加している最中に、翻訳元の .rst または .md ファイルを変更しないでください。翻訳した内容を .po ファイルに反映せずにを翻訳元を編集してしまうと、翻訳内容が消えてしまいます。翻訳元を編集したい場合は先に翻訳内容を .po ファイルに反映してください。反映方法は次のステップで紹介します。

12.2.1.9.2. 翻訳を .po ファイルに反映する#

.edit.po ファイルに翻訳を追加した後、.po ファイルへ翻訳を反映するのが、次のステップになります。.po ファイルは、最終的な翻訳ファイルになります。ファイルは、doc/locale/${LANGUAGE}/LC_MESSAGES 配下にあります。各 .rst または .md ファイルに対応しています。翻訳を編集したい場合は、対応する .edit.po ファイルを編集してから、変更内容を .po ファイルに反映し直す必要があります。

次のコマンドで、翻訳内容を .edit.po ファイルから .po ファイルへ反映します。

% cmake --build ../groonga.doc

例えば、この 導入 ページの日本語訳を行い、上記のコマンドを実行した場合、翻訳内容は、/doc/locale/ja/LC_MESSAGES/contribution/documentation/introduction.po ファイルに反映されます。

注釈

実は、翻訳を反映するコマンドは、翻訳用の .edit.po ファイルを生成するコマンドと同じコマンドです。なので、翻訳用のファイル生成と翻訳の反映で違うコマンドを覚える必要はありません。

12.2.1.9.3. HTMLファイルで翻訳を確認する#

翻訳が反映されたHTML形式のドキュメントをWebブラウザで確認できます。翻訳を .po ファイルに反映するステップにて、HTMLファイルも生成されています。これらのファイルは ../groonga.doc/doc/${LANGUAGE}/html/ 配下に生成されています。各ファイルは .rst または .md ファイルに対応しています。生成されたファイルをWebブラウザで開き、翻訳を確認できます。

例えば、導入 ページに日本語訳を追加した場合、次のコマンドで確認できます

% open ../groonga.doc/doc/ja/html/contribution/documentation/introduction.html

翻訳を確認して正しく反映されていたらパッチを送りましょう。送り方については、パッチを送るを参照してください。