
シリーズものの記事の第3弾です。さて、それではSphinxならではのディレクティブをいくつか使っていきます。また、それ以外にも、前回ので書き忘れたreSTなんかも補足していきます。トップ画像が代わり映えしなくて済みません。
前回書き忘れていた分
画像の挿入
ものすごく簡単です。
.. image:: tornado.png
これだけ。ファイルは、相対パスで指定します。上記の書き方をすると、そのファイルがあるのと同じフォルダを探索します。絶対パス/tornado.pngと書くとどうなるかというと、ソースコードの置いてあるルートのフォルダを起点に探索します。実際のファイルシステムのルートフォルダは探索しにいきません。
また、ビルドすると、デフォルト設定では、_build/html/_images以下にコピーされます。同じファイル名のファイルが複数あるとどうなるか・・・実験してみました。同じtornado.pngを、いろんなフォルダに置いておいて実行してみると、tornado.png, tornado1.pngなど連番がふられて、上書きされたり、といった事故は起きないようになっています。良くできていますよね。
インラインマークアップ
ちょくちょく使うのが、インラインマークアップ。等幅にしたり、太字にしたり。
コード例:**太字**, *イタリック*, ``等幅``
結果例:太字, イタリック, 等幅
注意点としては、前に書いたエントリーのリンクの説明と同様に、日本語混じりの文章の中に書く場合は、**太字** の前後にスペース、もしくは(),などの区切り文字がなければ識別されません。挟まっている文字列の前後にはスペースは不要です。アンダースコアをスペースと見なすと、_**太字にしたい文字**_といった感じにする必要があります。もしくは、\+スペースにすると、出力結果にスペースが入らないで、インラインマークアップを識別させることができます。日本語は単語区切りの言語ではないので、\+スペース(\_**太字にしたい文字**\_という表記をよく使うことになると思います。
リスト
他のテキストベースのマークアップとほぼ一緒です。
* Tornado(nginx; 4 frontend) * Tornado(1 single threaded frontend) * Django(Apache/mod_wsgi)
アスタリスクの代わりに、1. 2. 3. と書けば数値が前に付くリストも作成できますし、インデントして、その中にリストを書けば、複数階層のリストも書くことができます。ただし、階層が変わるところでは、前後に空行を1行いれる必要があります。
テーブル
テーブル(表)も作成できます。昔は日本語の扱いがおかしかったらしいのですが、今では問題なく扱えます。Tornadoでは使っていないので他所からサンプルをコピーしています。見出しセルの指定、セルの結合(横方向、縦方向)ができます。
+-------------+----------------------+---------+---------+------+ | Feature List | Python2 | Python3 | Ruby | +=============+======================+=========+=========+======+ | Push API | following_function | O | O | | + +----------------------+---------+---------+------+ | | following | O | O | O | +-------------+----------------------+---------+---------+------+ | Pull API | Queue | O | O | _ | +-------------+----------------------+---------+---------+------+
こちらが簡易表記です。縦方向のセルの結合はできません。これから説明していく、索引のまとめの表を作ってみました。後でもどってきて確認してみてください。
======= ==== ============== 入力 出力 ------------ -------------- 種類 引数 索引 ======= ==== ============== single: A; B A -> B single: A A pair: A; B A -> B, B -> A ======= ==== ==============
ブロックのディレクティブ
それでは、Tornadoの翻訳で使ったやつを中心に、Sphinxのディレクティブを説明していきます。
ノート、警告
こうすると、枠に囲まれて、少し強調させることができます。warningを使うと、警告メッセージを書くことができます。.. note:: オリジナルは http://www.tornadoweb.org/documentation にあります。
表題、画像へのリンク
.. _running_tornado_in_production: 本番環境でTornadoを実行する ============================ . . . 同様にFriendFeedのサーバはかならず :ref:`nginxを立てて` 運用していたため、
.. キーワード:を、表題や、画像のディレクティブの前に書くと、それをラベルとして設定することができます。その後、 :ref:`リンクの表示テキスト <リンク先のキーワード>`というのを文章中に書くと、表題などへのリンクを張ることができます。複数のソースコードに分かれていても、きちんとリンクを張ってくれます。
索引を作る
この索引機能は、すごく楽しいです。たくさん索引を付けたくなっちゃいます。これに使うのが、indexディレクティブです。これも、表題の前に付けます。二つの表題を置いてみます。
.. index:: single: XSRF pair: 設定; xsrf_cookies pair: テンプレート関数; xsrf_from_html() クロスサイトリクエストフォージェリからの保護 -------------------------------------------- (本文) .. index:: pair: テンプレート関数; escape single: テンプレート関数; 自作 single: テンプレート テンプレート ------------ (本文)
ちょっと長いですが、この設定をした状態でビルドをすると、以下のような索引ができます。索引は、リレーションバーの右端の「索引(英語だとindex)」をクリックすると表示されるページです。
- escape
- テンプレート関数
- XSRF
- xsrf_cookies
- 設定
- xsrf_from_html()
- テンプレート関数
- テンプレート
- テンプレート関数
- escape
- xsrf_from_html()
- 自作
- 設定
- xsrf_cookies
作成されるルールですが、 single: キーワード と書くと、キーワードがそのままリンクに登録されます。pair: A; Bと、セミコロンで区切ると、A → Bと、B → Aの二つのリンクが作成されます。pair: テンプレート関数; escapeの結果は、'escape'の所にも表示されますし、'テンプレート関数'の所にも表示されています。single: 親; 子とすると、pairのうちの片方だけ(親→子)表示されます。
singleの階層付き、もしくはpairで共通の要素があれば、まとめられた項目が作成されます。もし、同じ要素が3つあれば、テンプレート [2] [3](全部「テンプレート」という名前だったとした場合)という感じで、すべての項目へのリンクが作成されます。
基本的にはこれでOK
一通り説明してきました。通常のドキュメントを作成する分には、このあたりの使い方ができれば、便利なWiki以上の使い方ができるかな、と思います。Pythonプログラマであれば、 .. function::ディレクティブなどのディレクティブを使うと、ソースコードのドキュメントを作成するのも簡単にできるようになります。リンクするときも、:func:, :class:など、単語の型を明記した記述ができますので、整理された文章が書きやすいという特徴があります。このあたりは、リンクされる側の説明、リンクする側の説明をご覧ください。
次は、PDF出力あたりをブログに書きたいのですが・・・ちょっと苦戦中です。