12.2.1. Introduction — Groonga v16.0.5 documentation

Skip to main content
`Ctrl`+`K`

# 12.2.1. Introduction

This document outlines the procedures for writing, generating, and managing Groonga’s documentation. By following the steps below, you can contribute to enhancing and updating Groonga’s documentation.

## 12.2.1.1. How to fork and clone Groonga repository

Contributing to Groonga’s documentation begins with forking and cloning the Groonga repository. These actions are essential first steps that enable personal modifications and experimentation in your personal repository. And also, it enables you to submit them as your contributions to the Groonga repository. Follow these steps.

1. Go to groonga/groonga on GitHub

2. Click the `Fork` button to create a copy of the repository

3. Clone your Groonga repository with the following command

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

## 12.2.1.2. Install dependent software

Groonga uses Sphinx as documentation tool.

Here are command lines to install 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. Run `cmake` with `--preset=doc`

Groonga disables documentation generation by default. You need to enable it explicitly by adding `--preset=doc` option to `cmake`:

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

Now, your Groonga build is documentation ready.

## 12.2.1.4. Generate HTML

You can generate HTML by the following command:

    % cmake --build ../groonga.doc

You can find generated HTML documentation at `../groonga.doc/doc/en/html/`.

## 12.2.1.5. How to edit documentation

The Groonga documentation is written in reStructuredText (.rst) or Markdown (.md) . These files are located in the `doc/source`. Each page of the documentation corresponds to a `.rst` file or a `.md` file. By modifying the corresponding file, you can edit the target document. For Example, if you want to edit this Introduction page, you should edit the `doc/source/contribution/documentation/introduction.rst` file. Please find the file you wish to edit and make your changes.

## 12.2.1.6. How to add a new documentation

If you want to add a new documentation, you need to add the new documentation into `doc/files.am` and `doc/files.cmake` by the following command lines.

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

Note that you need to commit not only the new documentation but also `doc/files.am` and `doc/files.cmake` in this case.

## 12.2.1.7. Preview changes on HTML files

You can preview your documentation changes in your browser in HTML format. Follow these two steps.

1. Generate the HTML files with your changes

2. Preview the generated HTML files in your Web browser

### 12.2.1.7.1. Generate the HTML files with your changes

Use the following command to generate HTML files that reflect your changes. The generated files will be located in `../groonga.doc/doc/en/html/`. Each file corresponds to a `.rst` or `.md` file:

    % cmake --build ../groonga.doc

### 12.2.1.7.2. Preview the generated HTML files in your Web browser

Open the generated file in your Web browser to preview your changes. For example, if you have edited this Introduction page, you can preview it by the following command:

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

## 12.2.1.8. Send patch

You can submit your patch to the Groonga repository on GitHub via a pull request. Feel free to send a pull request by following these steps.

- Enable preview on your fork (optional)

- Prepare your pull request

- Submit your pull request

### 12.2.1.8.1. Enable preview on your fork (optional)

You can enable preview on your fork by following the steps below before pushing your commits:

1. Enable GitHub Pages on your fork:

   - Open `https://github.com/${YOUR_GITHUB_ACCOUNT}/groonga/settings/pages`

   - Select “GitHub Actions” as “Source”

2. Accept publishing GitHub Pages from all branches on your fork:

   - Open `https://github.com/${YOUR_GITHUB_ACCOUNT}/groonga/settings/environments`

   - Select the “github-pages” environment

   - Change the default “Deployment branches and tags” rule:

     - Press the “Edit” button

     - Change the “Name pattern” to `*` from `main`

You can preview your changes at the following URLs after pushing your changes:

- `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. Prepare your pull request

Ensure your changes are committed and then push your changes to your fork repository on GitHub. Follow these commands:

    % 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. Submit your pull request

Now you’re ready to submit a pull request to the upstream Groonga repository. Follow these steps:

1. Go to your fork repository on GitHub

2. Click the `Compare & pull request` button

3. Make sure your changes are reflected

4. Click the `Create Pull Request` button and send your pull request

## 12.2.1.9. Optional: Translate documentation

This is an optional step.

After editing and previewing the Groonga documentation, the next step is to translate the documents to make them accessible to a wider range of Groonga community users. Translating into languages other than English ensures that non-English speakers can also understand the Groonga documentation. Follow these steps to translate Groonga documentation.

1. Translate the documentation in `.edit.po` files

2. Reflect translations to `.po` files

3. Preview translations on HTML files

### 12.2.1.9.1. Translate the documentation in `.edit.po` files

Use the following command to generate `.edit.po` files, which are translation files, corresponding to your changes. The generated files will be located in `../groonga.doc/doc/locale/${LANGUAGE}/LC_MESSAGES`. Each file corresponds to a `.rst` or `.md` file. Please add your translations to `.edit.po` files:

    % cmake --build ../groonga.doc

For example, if you have edited the Introduction page and want to add Japanese translations, update this `../groonga.doc/doc/ja/LC_MESSAGES/contribution/documentation/introduction.edit.po` file.

Caution

Please do not modify the `.rst` or `.md` files while adding translations to the `.edit.po` files. Editing `.rst` or `.md` files without first reflecting the translations in `.po` files will result in the loss of those translations. If you want to edit `.rst` or `.md` files, ensure you first reflect your translations in `.po` files. The method to reflect translations will be introduced in the next step.

### 12.2.1.9.2. Reflect translations to `.po` files

After adding your translations to the `.edit.po` files, the next step is to reflect these translations to the `.po` files. `.po` files are the finalized translation files. These `.po` files are located in `doc/locale/${LANGUAGE}/LC_MESSAGES`. Each file corresponds to a `.rst` or `.md` file. If you want to edit your translations, edit the corresponding `.edit.po` file and then reflect your changes to the `.po` file.

To reflect translations from the `.edit.po` files to the `.po` files, use the following command:

    % cmake --build ../groonga.doc

For example, if you have added Japanese translations about the Introduction page and then execute the command above, your translations will be reflected to `/doc/locale/ja/LC_MESSAGES/contribution/documentation/introduction.po` file.

Note

Actually, the command to generate translation `.edit.po` files is the same as the one used for reflecting translations. Therefore, there’s no need to memorize different commands for generating translation files and reflecting the translations.

### 12.2.1.9.3. Preview translations on HTML files

You can preview your translations in your Web browser in HTML format. The step for reflecting translations into `.po` files also generates the corresponding HTML files. These files are located in `../groonga.doc/doc/${LANGUAGE}/html/`. Each file corresponds to a `.rst` or `.md` file. Open the generated HTML file in your Web browser to review your translations.

For example, to preview the Japanese translation of the Introduction page, use the following command:

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

If the translations seem correct after preview, please send a patch. For more information on this process, see the Send patch