渋日記@shibu.jp

シリーズものの記事の第3弾です。さて、それではSphinxならではのディレクティブをいくつか使っていきます。また、それ以外にも、前回ので書き忘れたreSTなんかも補足していきます。トップ画像が代わり映えしなくて済みません。

1. Pythonって何？という人のためのSphinxインストール入門
2. Pythonって何？という人のためのSphinxチュートリアル

前回書き忘れていた分

画像の挿入

ものすごく簡単です。

.. 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. と書けば数値が前に付くリストも作成できますし、インデントして、その中にリストを書けば、複数階層のリストも書くことができます。ただし、階層が変わるところでは、前後に空行を１行いれる必要があります。

テーブル

テーブル(表)も作成できます。昔は日本語の扱いがおかしかったらしいのですが、今では問題なく扱えます。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のディレクティブを説明していきます。

ノート、警告

.. 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で共通の要素があれば、まとめられた項目が作成されます。もし、同じ要素が３つあれば、テンプレート [2] [3](全部「テンプレート」という名前だったとした場合)という感じで、すべての項目へのリンクが作成されます。

基本的にはこれでOK

一通り説明してきました。通常のドキュメントを作成する分には、このあたりの使い方ができれば、便利なWiki以上の使い方ができるかな、と思います。Pythonプログラマであれば、 .. function::ディレクティブなどのディレクティブを使うと、ソースコードのドキュメントを作成するのも簡単にできるようになります。リンクするときも、:func:, :class:など、単語の型を明記した記述ができますので、整理された文章が書きやすいという特徴があります。このあたりは、リンクされる側の説明、リンクする側の説明をご覧ください。

次は、PDF出力あたりをブログに書きたいのですが・・・ちょっと苦戦中です。