reStructuredTextでドキュメントを書くときの最低限の規約

最近、SphinxでreST(reStructuredText)でドキュメント書いてます。 Microsoft Officeに比べて複数人で分担して書くときは便利ですね。バージョン管理もできるし。

reSTはいろいろな書き方ができるで、人によって差異がでてきます。最初のうちはいいんですが、ドキュメントが肥大化してくるとメンテナンスしずらくなります（というか人のを見ていてイライラしてくる）。

そこで、最低限これだけは統一しておこうと決めた規約について紹介します。いまのところ、これらを守るだけでも大分ましです。

文章の階層

階層の区切りはいろいろ表現できるけど、以下に統一。長さも揃える。

A. Chapter
********************************************************************************

A.B Section
================================================================================

A.B.C Subsection
--------------------------------------------------------------------------------

A.B.C.D Subsubsection
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

A.B.C.D.E Paragraph
""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""

A.B.C.D.E.F ?
''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''

（実際は A.とかは書かなくてよい。）これ以上の階層は作成しないこと。原則E階層までにすること。Fまでくるとそもそも構成がおかしい可能性が高いのでよく見直すこと。

テーブル

テーブルもいろいろな書き方があるけど、list-tableに統一

.. list-table::
   :header-rows: 1
   :widths: 75 25

   * - Product
     - Version
   * - Oracle JDK
     - 1.7.0\_45
   * - Glassfish
     - 4
   * - Oracle Database
     - 12c

アスキーアートテーブルは変更に弱く、メンテナンスしづらいので使用しない。アスキーアートテーブルでしか表現できない場合は、他の表現を考える。

ソースコードの説明

.. code-block:: java

    public class Main {
        public static void main(String[] args) { // (1)
            System.out.println("Hello World"); // (2)
        }
    }


.. list-table:: 
   :header-rows: 1
   :widths: 10 90


   * - 項番
     - 説明
   * - | (1)
     - | コマンドラインで実行する際に、エントリポイントとなるメソッドの決まり事です。
   * - | (2)
     - | 標準出力に"Hello World!"を出力します。

ソースコード中にコメントで番号を振り、テーブルで各番号に対して説明を書く。

構造化された(技術)ドキュメントを書くのであれば、上記を守るだけでもかなり統制がとれます。細かい部分までガチガチにきめると規約を見るのが面倒になりますし、いらないような気がしています。

IK.AM