ドキュメントスタイルガイド¶
基本的なrst文章の書き方については以下が参考になります。
- Sphinxドキュメント — Sphinx documentation
- 逆引き辞典 :: ドキュメンテーションツール スフィンクス Sphinx-users.jp
- Documentation style guide — Style guide for Sphinx-based documentations 0.1dev documentation
- Sphinxでドキュメントを書くためreST記法に入門した - kk_Atakaの日記
- Sphinxを使ってプログラムドキュメントを楽しく書こう - maru source
用語の統一について¶
いくつか利用頻度の高い用語については、統一した記法を用います。
- Buster.JS
Buster.JS のテスティングフレームワーク自体を示す。 公式サイトの記法と同じ、 “Buster.JS” という表記に統一する
|Buster.JS| という置換記法を利用する事で用語集へのリンクをつけたものに置換される
- buster.js(設定ファイル)
Buster.JSで用いる buster.js というファイル名の設定ファイルの事。 “buster.js設定ファイル” 又は” buster.js 設定ファイル “という表記を使う
|buster.js| という置換記法を利用する事で用語集へのリンクをつけたものに置換される。 buster.js(設定ファイル)と毎回書くのは冗長なため |buster.js| と書くのを推奨する。
サンプルのコード表示について¶
azu/busterjs-kumite に置かれているサンプルコードを参照する場合は、 以下のような形で、サブモジュールにおいてあるコードを読み込んで利用する。
.. literalinclude:: /busterjs-kumite/getting-started/test/simple-node-test.js
:language: js
:linenos:
コードを読み込み表示する際に :linenos: で行番号を表示させる場合でも、 ファイルがいつ変更されるかわからないため、直接その行番号に対して言及するのはできるだけ避けるようにする。 1行目等、殆ど変わることがない場合はその限りではない。
直接コードを参照する場合、または azu/busterjs-kumite 以外のコードを参照する場合は コードディレクティブを用いて表示する。 その際に、シンタックスハイライトが出来る言語であるなら、正しく指定する
.. code-block:: js
var code = "サンプルコード";