12.2.1. 導入 — Groonga v16.0.5ドキュメント

本文へスキップ
`Ctrl`+`K`

# 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. フォーク先リポジトリでプレビューを有効にする（任意）

コミットをプッシュする前に、次の手順を実行することでフォークしたリポジトリ上でプレビューを有効にできます。

1. フォークしたリポジトリで GitHub Pages を有効にする。

   - `https://github.com/${YOUR_GITHUB_ACCOUNT}/groonga/settings/pages`を開く

   - "Source"に"GitHub Actions"を選択する

2. フォークしたリポジトリのすべてのブランチからGitHub Pagesの公開を許可する。

   - `https://github.com/${YOUR_GITHUB_ACCOUNT}/groonga/settings/environments`を開く

   - "github-pages"環境を選択する

   - デフォルトの"Deployment branches and tags"ルールを変更する

     - "Edit"ボタンを押す

     - "Name pattern"を`main`から`*`に変更する

変更をpushしたあと、次のURLで変更内容をプレビューできます。

- `https://${YOUR_GITHUB_ACCOUNT}.github.io/groonga/`

- `https://${YOUR_GITHUB_ACCOUNT}.github.io/groonga/ja/`

- `https://${YOUR_GITHUB_ACCOUNT}.github.io/groonga/reference/api/`

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

次のコマンドで、変更をコミットし、その変更を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.3. プルリクエストを送る

これで、アップストリームの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

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