執筆ドキュメント¶

バージョン管理システム利用指針¶

方針¶

ブランチ数を最小にする
作業単位で情報が分散しないようにする（凝集度を高める）
作業状況をわかりやすくする（チェックボックスにて進捗を管理する）

ブランチ一覧¶

master

少なくとも、査読、日本語警察実施済みの成果物を配置する

[翻訳範囲を示すブランチ]

該当範囲の翻訳、査読、日本語警察作業を行うため、masterから作成されるブランチで、作業後masterにマージされる

ブランチ名は、[a-zA-Z_0-9]からなる文字列で命名する
Tutorialの場合： tutorial[番号]_[タイトル]_[lesson][最初の番号]_[最後の番号]
Lectureの場合 : lecture[番号]_[タイトル]

user_[ユーザレビュー範囲を示すブランチ]

ユーザレビューで変更が必要な場合、masterから作成されるブランチで、作業後masterにマージされる

[ユーザレビュー範囲を示すブランチ]は、[翻訳範囲を示すブランチ]に準拠する

コミットルール¶

コミットは1つの目的の単位で行う（e.g. 新規追加と既存のリファクタリングを1つのコミットで行ったりするのは避ける）
コミットメッセージは、ここ 1 のライト版に従う

作業の流れ¶

1〜4に役割 2 を分けて作業を進める。但し、各作業フェーズに特化しない全体的な課題はIssueを作成して解決する。

翻訳（詳細はGitHub Wiki 3 を参照）
- 翻訳範囲を示すブランチを作成する
- （空）コミットを行う
- masterブランチに対し、Draft PR(Pull Request)を発行する
  - チェックボックスにて、作業進捗が分かるようにする
- 作成したブランチに翻訳コミットを追加していき翻訳を終わらせる
- 翻訳作業が終わったら、Draft PRをPRに変更し、PR上でReviewersに査読メンバーを追加した上で@mentionで通知する
査読
- PRに対して、コメントを記載していき査読を終わらせる
  - PRのFiles changedタブで差分を開き+アイコンをクリックしてコメントを追記
- 必要に応じて、翻訳者と連絡を取り合い査読を終わらせる
- 査読が完了したら、PR上でReviewersに日本語警察メンバーを追加した上で@mentionで通知する
日本語警察
- PRに対して、コメントを記載していき日本語警察を終わらせる
  - PRのFiles changedタブで差分を開き+アイコンをクリックしてコメントを追記
- 必要に応じて、翻訳者と連絡を取り合い日本語警察を終わらせる
- 日本語警察が完了したら、PRをマージする
ユーザレビュー
- 翻訳者の依頼を受け、指定された翻訳範囲のユーザレビューを行う
- 必要に応じて、翻訳者と連絡を取り合いユーザレビューを終わらせる
- 変更が必要な場合に限り以下を行う
  - 翻訳者がブランチを作成して修正を行い、PR上でReviewersにユーザレビューメンバーを追加した上でPRを発行し、@mentionで通知する
  - ユーザレビュー担当者が確認を行い、問題なければマージする

脚注

1: https://qiita.com/itosho/items/9565c6ad2ffc24c09364
2: https://github.com/tokyoquantopian/quantopian-doc-ja/wiki/%E5%BD%B9%E5%89%B2%E5%88%86%E6%8B%85
3: https://github.com/tokyoquantopian/quantopian-doc-ja/wiki/%E7%BF%BB%E8%A8%B3%E8%80%85%E4%BD%9C%E6%A5%AD%E3%83%A1%E3%83%A2

ファイルの作成とtoctreeへの登録¶

ディレクトリ構成¶

├── build
└── source
    ├── _static
    ├── _templates
    ├── conf.py
    └── index.rst

build: ビルド処理で生成されたHTMLやPDFが格納
source: 原稿のファイル（.rstや.ipynb）
source/index.rst: マスタドキュメント

章の立て方¶

source 直下に章名のディレクトリを作成する
作成したディレクトリに章のトップとなるファイル（例: title.rst）を作成する
source/index.rst のtoctreeに追加する

<例: 章の名前をSOS、トップとなるファイルをtitle.rstとした場合>

source/index.rst¶

.. toctree::
   :maxdepth: 2
   :caption: Contents:

   SOS/title

節の立て方¶

章のディレクトリに節単位でファイルを作成する
トップとなるファイルのtoctreeに作成したファイルを追加する

<例: 節ファイルabout.rstを追加する場合>

source/SOS/title.rst¶

.. toctree::
   :maxdepth: 2
   :caption: Contents:

   SOS/about

reSturedTextのルール¶

見出し¶

下記のようにします。必要であれば階層を増やしても問題ありません。

========
章見出し
========

節見出し
========

項見出し
--------

各見出しにはリファレンスできるよう、ラベルを記述します。名前が重複しないよう、ラベルは _章-節-項 の形式にします。

<例>

.. _sos:

=====
SOS団
=====

.. _sos-about:

SOS団とは
=========

.. _sos-about-history:

SOS団の歴史
-----------

番号は付与しません。自動的に割り振られます。

正）SOS団

誤）第1章 SOS団

Note、Warning¶

noteとwarningのみを用います。それ以外のディレクティブを使いたい場合はissueを上げて協議します。

"attention", "caution", "danger", "error", "hint", "important", "note", "tip", "warning", "admonition"

<例>

.. note:: これはnoteです

   tipsやhintも含みます

注釈

これはnoteです

tipsやhintも含みます

.. warning:: これはwarningです

   attentionやcautionも含みます

警告

これはwarningです

attentionやcautionも含みます

URL¶

脚注に記載します。 rubric:: ディレクティブは 節（ファイル）の最後 に記載します。

<例>

詳細については公式ドキュメント [#python_org]_ を参照してください。

.. rubric:: 脚注

.. [#python_org] https://docs.python.org/ja/3/index.html

詳細については公式ドキュメント 1 を参照してください。

強調¶

インラインリテラル ``word``: 関数、クラス、引数、値
強い強調 **word**: 初出のモジュール、クラス
強調 *word*: 上記以外

literalinclude:: ディレクティブで強調する場合は :emphasize-lines: オプションを用います。

<例>

.. literalinclude:: src/example.py
   :caption: example.py
   :language: python
   :emphasize-lines: 1,6-9
   :linenos:

example.py¶

def fizzbuzz(num):
    if num % 3 == 0 and num % 5 == 0:
        return 'FizzBuzz'
    elif num % 3 == 0:
        return 'Fizz'
    elif num % 5 == 0:
        return 'Buzz'
    else:
        return str(num)

for num in range(1, 101):
    print(fizzbuzz(num))

画像¶

figure:: ディレクティブを用います。 :name: オプションとキャプションをつけます。

<例>

.. figure:: https://www.python.org/static/img/python-logo.png
   :name: python_logo

   ここがキャプションになります

ここがキャプションになります¶

参照する場合は :numref: ロールを用います。

これはPythonの画像です（ :numref:`python_logo` ）

これはPythonの画像です（図 1 ）

表（テーブル）¶

次のディレクティブを用います。 :name: オプションとキャプションをつけます。

<例>

list-table
cst-table
table（grid tableはできるだけ使わない）

.. list-table:: 好きな食べ物
   :name: foods
   :header-rows: 1

   * - なまえ
     - 食べ物
   * - 長門
     - カレー
   * - 小泉
     - りんご

好きな食べ物¶
なまえ	食べ物
長門	カレー
小泉	りんご

参照する場合は :numref: ロールを用います。

<例>

団員の好きな食べ物を :numref:`foods` に示します。

団員の好きな食べ物を表 1 に示します。

クロスリファレンス¶

脚注 + :ref: ロールを用います。

nbsphinx [#ref1]_ を用います。

.. rubric:: 脚注

.. [#ref1] :ref:`nbsphinx`

nbsphinx 2 を用います。

索引¶

<例>

:index: ロールを用います。

:index:`SOS団` は世界を大いに盛り上げる為の涼宮ハルヒの団です。

SOS団は世界を大いに盛り上げる為の涼宮ハルヒの団です。

コード¶

コマンドは code-block ディレクティブを用います。言語名を明記し、 :name: および :caption: オプションをつけます。

<例>

.. code-block:: python
   :name: zen_of_python
   :caption: Zen of Python

   import this

Zen of Python¶

import this

参照する場合は :numref: ロールを用います。

<例>

:numref:`zen_of_python` を実行します。

リスト 4 を実行します。

Pythonスクリプトを参照する場合は literalinclude:: ディレクティブを用います。 :linenos: オプションで行番号を表示します。コードの途中から切り出す場合は :lines: オプションでとりだす行番号を指定し、 :lineno-start: オプションで行番号を振り直します。

<例>

.. literalinclude:: src/example.py
   :caption: example.py
   :language: python
   :lines: 11-
   :lineno-start: 11
   :linenos:

example.py¶

for num in range(1, 101):
    print(fizzbuzz(num))

ターミナル¶

次のOSを対象とします。

Windows
macOS
Linux(Ubuntu)

コマンドは code-block ディレクティブを用い、ハイライトする言語は次のとおりにします。macOSのシンタックスはzshとなっていますが、内容はbashで構いません。

ターミナルブロックのルール¶
OS	言語	caption	プロンプト
Windows	powershell	冒頭に[Win] をつける	>
macOS	zsh	冒頭に[macOS] をつける	$
macOS/Linux	bash	冒頭に[macOS/Linux] をつける	$
Windows/macOS/Linux	bash	冒頭に[Win/macOS/Linux] をつける	$

<例>

.. code-block:: powershell
   :caption: [Win] 仮想環境を有効化

   > venv\Scripts\activate.ps1

[Win] 仮想環境を有効化¶

> venv\Scripts\activate.ps1

TODO¶

TODOを残しておく場合は todo:: ディレクティブを用います。

<例>

.. todo:: 宇宙人の正体

   あとで詳しく書く

課題

宇宙人の正体

あとで詳しく書く

脚注

1: https://docs.python.org/ja/3/index.html
2: nbsphinx

文章のルール¶

敬体と常体¶

ですます調にします。

誤: pip install jupyter で Jupyter をインストールできる。
正: pip install jupyter で Jupyter をインストールできます。

全角と半角¶

全角の英数は使用しません。リテラルを使わない場合は前後のスペース不要です。

数値¶

3桁ごとに , 区切りを入れます。

誤: 来場者は2000人に達しました
正: 来場者は2,000人に達しました

日付¶

文章中に日付が必要な場合は以下のフォーマットで記述します。必ず「年」を含めます。

2016年3月14日
2016年12月25日

プログラミングコード中の日付は、可能であれば YYYY-MM-DD とします。

2016-03-14
2016-12-25

言語やライブラリの仕様、その他の制約がある場合はこの限りではありません。

固有名詞¶

固有名詞は大文字・小文字を含めて正確な表記を用います。

誤: numPyは行列計算のためのパッケージです。
正: NumPyは行列計算のためのパッケージです。

略称を用いる場合は、最初に登場する箇所で正式名称を記述した上で、括弧書きで略称を示します。

World Wide Web Consortium（以下 W3C）は Web技術

Pythonのバージョンが必要な場合はマイナーバージョンを表記し、バージョンの前にはスペースを空けます。

Python 3.5

パッケージのバージョンを示す場合は原則パッチバージョンまで含めます。

NumPy 1.11.0

ただし、MEASURE.MINOR.PATCH でバージョニングされていない場合は配布元のバージョニングに従います。

http://semver.org/

コード解説のルール¶

関数¶

「<関数名>() 関数」とし、サフィックスをつけます。

``print()`` 関数を実行します。

クラス¶

「クラス名 クラス」とし、サフィックスをつけます。クラスの所属元のモジュール名は付与しません。

``DataFrame`` クラス

メソッド¶

「<メソッド名>() メソッド」とし、サフィックスをつけます。

``plot()`` メソッドを実行します。

メソッドの所属クラスを明記した方が説明上都合がよい・または分かりやすい場面ではクラス名を記述します。

``DataFrame.plot()`` メソッドを実行します。

メソッドの所属オブジェクトを明記した方が説明上都合がよい・または分かりやすい場面ではオブジェクト名を記述します。

``df.plot()`` メソッドを実行します。

位置引数¶

「第<位置>引数 」とします。

``print()`` の第1引数には値を渡します。

キーワード引数¶

「引数 <引数名> 」とします。

``print()`` の引数 ``end`` に文字列を渡すと、末尾の出力文字列を指定できます。

返り値、戻り値¶

「返り値」とします。

``sum()`` の戻り値はスカラ型またはSeries型になります。

ドキュメントのビルド¶

環境構築¶

ビルドにライブラリをインストール。

pip install sphinx

HTML¶

make html

build/html に index.html が生成される。

Dockerからビルドする場合。

docker run --rm -v $PWD:/build driller/nbsphinx-build:requirements make html

PDF¶

事前に TeX Live をインストール。

make latexpdf

build/latex に projectname.pdf が生成される。

Dockerからビルドする場合。

docker run --rm -v $PWD:/build driller/nbsphinx-build:requirements make latexpdf

textlint¶

使用するルールプリセット¶

ルールの追加¶

quantopian-doc.yml に追記します。

<例>

version: 1
rules:
  - pattern: 取引アルゴリズム
    expected: トレーディングアルゴリズム

インストール¶

Docker（後述）から実行する場合は不要です。

npm install --save-dev \
textlint \
textlint-rule-preset-ja-technical-writing \
textlint-rule-preset-jtf-style \
textlint-rule-prh \
textlint-plugin-rst

pip install docutils-ast-writer

実行¶

.rstファイルの場合

textlint <path_to_rst>

.ipynbファイルの場合

jupyter nbconvert <path_to_ipynb> \
  --to rst --stdout \
  --TemplateExporter.exclude_code_cell=True | \
  textlint --stdin

Dockerから実行する場合 textlint コマンドのpathの先頭に /work をつけます

docker run --rm -v $PWD:/work driller/textlint-rst textlint /work/<path_to_rst>

執筆ドキュメント¶

バージョン管理システム利用指針¶

方針¶

ブランチ一覧¶

コミットルール¶

作業の流れ¶

ファイルの作成とtoctreeへの登録¶

ディレクトリ構成¶

章の立て方¶

節の立て方¶

reSturedTextのルール¶

見出し¶

Note、Warning¶

URL¶

強調¶

画像¶

表（テーブル）¶

クロスリファレンス¶

索引¶

コード¶

ターミナル¶

TODO¶

文章のルール¶

敬体と常体¶

全角と半角¶

数値¶

日付¶

固有名詞¶

コード解説のルール¶

関数¶

クラス¶

メソッド¶

位置引数¶

キーワード引数¶

返り値、戻り値¶

ドキュメントのビルド¶

環境構築¶

HTML¶

PDF¶

textlint¶

使用するルールプリセット¶

ルールの追加¶

インストール¶

実行¶

Indices and tables¶