Sphinx Advent Calendar 2012 (全部俺)

初心者がどのようにSphinxを使ってきたかという記録

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

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

reStructuredText を覚えよう!

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

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

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

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

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

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

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

    新しい現場での利用ツール申請
    ==============================
    
    TortoiseHg編
    -------------
    私「利用希望ツールの件ですがリスト作成しましたのでご確認お願い致します」
    
    
    :バージョン管理ツール: TortoiseHg
    :ファイラ: あふw
    :エディタ: 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編
    ---------
    リーダー「ファイラって何?」
    
    私「エクスプローラのようにファイルを効率よく操作する為のツールです」
    
    リーダー「なるほど。しかし名前が怪しげだねぇ『あふw』って」
    
    私「確かに名前は変ですが10年以上利用しており信頼性も高いツールです」
    
    リーダー「でもねぇ、あふwって。あふwwww」
    
    被害にあったツール
    ~~~~~~~~~~~~~~~~~~~
    * あふw
    
    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/

今回は、

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

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

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