8.3. How to contribute in documentation topics — Mroonga vmrn_version documentation

Skip to main content
`Ctrl`+`K`

# 8.3. How to contribute in documentation topics

We use Sphinx for documentation tool.

具体的にどんなことをやればいいのかを説明します。基本的にはドキュメントのソースファイルごとにpull requestを送ってもらうと進めやすいです。

対象となるファイルはdoc/sourceディレクトリ以下の拡張子が「.rst」となっているファイルです。

あまりGitHubでの作業に慣れていなくてもできるように、「最初にやること」と「作業ごとにやること」、「ファイルごとにやること」に分けて順に説明します。

- The things you must do at first

- The things you need to do every tasks

- The things you need to do every files

## 8.3.1. The things you must do at first

以下では、最初に一度だけ実施しておけば良いことを説明します。

### 8.3.1.1. Git configuration

まずは、gitの設定をしましょう。すでにある程度gitを使っている場合には初期設定はすでに完了しているかも知れません。その場合には飛ばして構いません。

    $ git config --global user.name "Your Name"
    $ git config --global user.email "Email address"

上記はコミットログに使われます。公開しても差し支えないユーザ名もしくはメールアドレスを設定します。

### 8.3.1.2. Fork on GitHub

First, create GitHub account. If your GitHub account is ready, login to GitHub and access following URL.

- Fork the Mroonga repository

Fork リポジトリ選択画面でご自分のリポジトリへとforkしてください。

### 8.3.1.3. Initial configuration for working repository

Clone Mroonga repository to working directory. Don’t forget to do “Git configuration”.

    $ git clone git@github.com:(YOUR_GITHUB_ACCOUNT)/mroonga.git
    $ cd mroonga
    $ git remote add upstream git@github.com:mroonga/mroonga

### 8.3.1.4. Prerequisites

Before generating the Mroonga documentation, we need to build Mroonga. Please refer to Others for the instructions on how to build Mroonga.

### 8.3.1.5. Required software

Generating Mroonga documentation needs the followings.

- Sphinx

- gettext gem

We use Sphinx for documentation tool and use gettext gem for localization. You can install both tools using the following commands.

    $ pip install -r doc/requirements.txt
    $ (cd doc && bundle install)

### 8.3.1.6. Initial configuration for building documentation

Execute following commands to prepare for generating Mroonga documentation.

    $ cmake \
        -S . \
        -B ../mroonga.doc \
        --preset=doc \
        -DMYSQL_SOURCE_DIR=(MySQL_SOURCE_DIRECTORY) \
        -DMYSQL_BUILD_DIR=(MySQL_BUILD_DIRECTORY) \
        -DMYSQL_CONFIG=(MySQL_CONFIG)

Next step is “The things you need to do every tasks”.

## 8.3.2. The things you need to do every tasks

以下では作業ごとにやることを説明します。

### 8.3.2.1. Follow the upstream

Mroonga本家の最新状態に追従して、作業がかぶらないようにします。

    $ git fetch --all
    $ git checkout main
    $ git rebase upstream/main

最新の状態に追従できたら、「ファイルごとにやること」へと進みます。

## 8.3.3. The things you need to do every files

以下では、例えば The characteristics of Mroonga を更新する場合で説明します。作業対象となるファイルは、リポジトリのdoc/source/ディレクトリ以下にあり拡張子が.rstなファイルです。今回は、doc/source/characteristic.rstを変更する例で説明します。

### 8.3.3.1. Create working branch

Create a working branch. Use meaningful branch name.

    $ git checkout -b use-capitalized-notation-characteristic

### 8.3.3.2. Editing text

Fix typos, styles or write a new document for Mroonga.

### 8.3.3.3. Confirm generated document

Execute following command to generate HTML files that reflect your changes.

    $ cmake --build ../mroonga.doc

Open the generated file in your Web browser to preview your changes are reflected.

    $ open ../mroonga.doc/doc/en/html/characteristic.html

### 8.3.3.4. Commit

HTMLに問題がないことを確認できたら、コミットします。

    $ cd ${cloneしたディレクトリーのトップディレクトリー}
    $ git add doc/source/characteristic.rst
    $ git commit

コミットするときのメッセージについては、例えば以下のようにします。

    doc: use "Mroonga" notation

### 8.3.3.5. Push and pull request

Publish your changes to your own GitHub repository.

    $ git push -u origin use-capitalized-notation-characteristic

Note that `use-capitalized-notation-characteristic` is already created branch in advance.

ブラウザで `https://github.com/(GitHubのアカウント)/mroonga` を開くと「 @use-capitalized-notation-characteristic@ 」ブランチをpull requestする！みたいなUIができているので、そこのボタンを押してpull requestしてください。入力フォームがでてきますが、コミットしたときメッセージで十分なのでそのままpull requestしてOKです！

これで、ひととおりの作業は完了しました。