Ctrl+K

12.2.1. 導入#

この文書では、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. HTMLファイルで変更を確認する#

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

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

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

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

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

% cmake --build ../groonga.doc

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

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

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

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

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

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

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

12.2.1.7.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.8. 更新#

ドキュメントのソースは doc/source/ にあります。ソースは英語で書かれているはずです。ドキュメントの翻訳方法については、国際化 をご覧ください。

既に存在するドキュメントのファイルを更新すると、翻訳対象のファイルを更新できます。

On this page