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 リポジトリ選択画面でご自分のリポジトリへと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.

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です！

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