警告

この記事は古い為 sphinx-users.jp を参照してください。

第4日目 Sphinxドキュメントを編集する その１

今度こそ、Sphinxドキュメントの作成に入ります。

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/

今回は、

  • インラインマークアップ(文字の修飾)

  • タイトルリファレンス

  • 番号無しリスト(箇条書き)

  • 番号付きリスト(箇条書き)

  • セクション(ブロックの区切り)

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

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

第3日目 Sphinxドキュメントを書く道具   第5日目 Sphinxドキュメントを編集する その２