reStructuredText を覚えよう！

• Sphinxドキュメントは reStructuredText という記法を使用して、テキストファイル(拡張子.rst)を作成します。

reSTファイル(拡張子 .rst)の編集例

まず、実際にコピペでSphinxドキュメントを作成してみましょう。

1. index.rst をテキストエディタで開きます。

2. 記載してある内容を全て削除してください。 index.rst は sphinx-quickstart を打てば何度でも作成できますのでバックアップは不要です。

3. 文字コードを UTF-8 に変更して下さい。サクラエディタを利用しているのならば ここ を参考にして下さい。 Vim を使っているならば :set fenc=utf8 ですね。その他のエディタについては各自で調べて下さい。

4. 次の内容をコピー＆ペーストし、上書き保存してください。

   新しい現場での利用ツール申請
   ==============================
   
   TortoiseHg編
   -------------
   私「利用希望ツールの件ですがリスト作成しましたのでご確認お願い致します」
   
   
   :バージョン管理ツール: TortoiseHg
   :ファイラ: あふｗ
   :エディタ: Vim
   :ランチャ兼スクリプトエンジン: AutoHotKey
   :プログラミング言語処理系: Python
   :シェル: nyaos
   :ターミナルエミュレータ: ckw
   :UNIXライク環境: Cygwin
   :ターミナルエミュレータ: ck
   
   リーダー「ふむ、 **バージョン管理ツール** は要らないでしょう。 *ファイル名に日付* とか付けて保存しといてよ」
   
   被害にあったツール
   ~~~~~~~~~~~~~~~~~~~
   * TortoiseHg
   * 他、バージョン管理という概念
   
   Python編
   ---------
   リーダー「 **Python** って何に使うの？」
   
   私「色々と便利な拡張を入れたり手軽にスクリプトを書いたりですね、」
   
   リーダー「うーん、そんなに色々と作成してくれなくても大丈夫だから」
   
   被害にあったツール
   ~~~~~~~~~~~~~~~~~~~
   1. Mercurial
   2. Sphinx
   3. fabricその他
   4. 他、自動化という概念
   
   Vim編
   ------
   リーダー「なになにヴィ...？」
   
   私「 **ビム** です」
   
   リーダー「もう少し *メジャーなツール* は無いの？」
   
   私「 **Vim** は全世界的に使われているエディタで、秀丸の数倍、いや数千倍のユーザ数を誇りLinuxディストリの99%に同梱されている、これぞメジャー！」
   
   リーダー「 *サクラエディタ* じゃダメかな」
   
   私「はい、喜んで！」
   
   Vimはサクラエディタ以下の知名度！
   
   被害にあったツール
   ~~~~~~~~~~~~~~~~~~~
   * Vim
   
   あふｗ編
   ---------
   リーダー「ファイラって何？」
   
   私「エクスプローラのようにファイルを効率よく操作する為のツールです」
   
   リーダー「なるほど。しかし名前が怪しげだねぇ『あふw』って」
   
   私「確かに名前は変ですが10年以上利用しており信頼性も高いツールです」
   
   リーダー「でもねぇ、あふwって。あふwwww」
   
   被害にあったツール
   ~~~~~~~~~~~~~~~~~~~
   * あふｗ
   
   Cygwin編
   ---------
   私(号泣しながら)「こ、これではあまりにも非効率すぎます。せめてCygwinだけでも！」
   
   リーダー「ああCygwinとWinmergeは前例があるからいいよ」
   
   私(狂喜)「よっしゃー！Python,Mercurial,Sphinx,Vimゲット！！！」
   
   ゲットしたツール
   ~~~~~~~~~~~~~~~~~~
   A. Python
   B. Mercurial
   C. Sphinx
   D. Vim
   E. その他なんでも
   F. 番外編でCygwinのVimのパス ``C:\cygwin\bin\vim-nox.exe`` *vim-nox* が実体らしい
   

5. 張り付けたらコマンドプロンプトより index.rst があるディレクトリに移動し make html を実行して下さい。

6. 下記ディレクトリの html をブラウザで閲覧して下さい。

   index.rst があるディレクトリの \_build\html\index.html

   下記リンクのように表示されるはずです。

   http://usaturn.net/sample/01/

今回は、

• インラインマークアップ(文字の修飾)
• タイトルリファレンス
• 番号無しリスト(箇条書き)
• 番号付きリスト(箇条書き)
• セクション(ブロックの区切り)

を利用してサンプルを作成しました。詳しくは明日、説明しますので、どのように書くと、どのように表示されるかを確認してみてください。

※ このアドベントカレンダーについては このアドベントカレンダーについて を参照して下さい。

テキストエディタを使おう

ドキュメント作成を始める前に、ちょっと待って下さい！あなたは普段、どんなテキストエディタを使ってますか？ もしもWindows標準の メモ帳 を使っているのなら、

文字コードをUTF-8に変更できるテキストエディタ

を探して来て下さい。もしもよくわからなければ、今日は サクラエディタ の使い方を覚えましょう。

• 秀丸、Emacs、Vim、Eclipse等々、既にお気に入りのエディタやIDEがあるのなら、今日は読み飛ばして下さい。