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. 事前に必要な対応#

Mroongaのドキュメントを生成する前に、まずMroongaをビルドする必要があります。Mroongaのビルド方法については、その他を参照してください。

8.3.1.5. 必要なソフトウェア#

Mroongaのドキュメントを生成するためには、以下が必要です。

ドキュメントツールとしてSphinxを使用し、ローカライズにはgettext gemを使用します。以下のコマンドでこれらのツールをインストールできます。

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

8.3.1.6. ドキュメント生成の初期設定#

下記のコマンドで、Mroongaドキュメントを生成する設定をします。

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

次のステップは、"ドキュメント編集・更新時に毎回必要な作業"の説明をします。

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#

以下では、例えば 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. 生成されたドキュメントを確認#

下記のコマンドで、変更内容を反映したHTMLを生成します。

$ cmake --build ../mroonga.doc

変更が反映されたHTML形式のドキュメントをWebブラウザで確認します。

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

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