ドキュメントのフォーマット

すべてのドキュメントは標準wikiマークアップではなく、ReStructuredTextフォーマットで書きます。これはドキュメントの価値を長期間保持するためにとても重要なことです。私たちは将来Docudoにドキュメントを移行する予定でいます。そしてReStructuredTextを使うことで、複雑なドキュメントの変更なしに移行することが可能になるのです。

あなたのドキュメントに使われるテンプレートは２つあります。両方のテンプレートはフォーマットをReSTにセットしてあり、コメントフォームを含むように適切なコードを含んでいます。

公式テンプレート 公式ドキュメントのためのもので、これはエディタだけが編集できるようにしてあります。 TurboGears?テンプレート 非公式ドキュメントのためのものです。

MoinMoin?には ReStructuredText?入門ページ と MoinMoin?でReSTを使う というページがあります。

正しい場所へドキュメントを書く

TurboGears?フレームワークに関するすべてのドキュメントはページ名のはじめにwikiシンタクスでバージョンナンバーを 持たなければなりません 。もしあなたがTurboGears 1.0のApacheデプロイに関するページを書くのならば、ページの名前は1.0/ApacheDeployment?となります。MoinMoinのReSTパーサはwikiワードリンクを自動的には生成しませんので、ReSTのリンクシンタクスを使う必要があります:

`1.0/ApacheDeployment`_　はページ名のリンクをテキストとして生成します。
`Apache deployment <1.0/ApacheDeployment>`_　はよりわかりやすいテキストでリンクを生成します。

複数ページにわたるドキュメントではページを反映したサブwikiフォーマット、例えば1.0/20MinuteWiki/Page1のようなフォーマットを使います。

スタイルガイドライン

ドキュメントの一貫性を保つため、またオフラインでも便利に利用できるために、以下の書式に従ってください:

1. タイトルはアンダーラインのみで、順序は=、-、~、`です。

2. リテラルを使う対象はコード（変数名とパラメータを含みます）と、ターミナルに直接タイプするものすべてです。リテラルは``で囲みます。古い慣例によって"で囲んだリテラルがあった場合は、"を削除して``に置き換えてください。

3. コマンドラインはブロックリテラルになりますので、見やすくなります。``tg-admin info``と書く代わりに以下のように書いてください:

   tg-admin info
   

4. サンプルパッケージ名（例えばWiki 20）は``*packagename*``のように、そのpython名は``*appname*``（例えば``wiki_20``）と書いてください。

5. 各行は80文字に収まるようにしてください。

6. 推奨されるリンクシンタクスは、標準的なReSTの付記スタイルです:

   This is an `example link`_.
   
   .. _example link: 1.0/ExampleLink
   

7. リストにはリストを使い、太文字やイタリック文字などを使わないでください。これは引数などのリストを扱うときに便利になります。例えば 設定 のページを見てみてください:

   ``arg1``
      argument 1 explanation text
   ``arg2``
      argument 2 explanation text