========================== ドキュメントのパワーアップ ========================== Sphinxには様々なマークアップがあります。これを利用すると、見やすく情報量の豊富なドキュメントを作ることができます。 .. contents:: ここで紹介するマークアップ一覧 :local: インラインマークアップ ====================== 太字、斜体、リテラルなどが利用できます。 .. code-block:: rst **太字** *斜体* ``リテラル`` `リンク付きテキスト `_ コードブロック ============== ライセンス文の表記や、ソースファイルなどをドキュメント中で表現する、コードブロックがあります。コロンは前の段落の末尾に付けることもできます。また、ブロックの前後には空行を入れてください。 .. code-block:: rst :: 本ドキュメントはフィクションです。登場する人物、 企業名は架空のものです。 ソースコードを入れる場合には、言語名を指定することで、コードハイライトが行えるディレクティブがあります。Pygmentsというライブラリを利用しているため、日常使われるプログラミング言語やマークアップなどはかなり網羅しています。 .. code-block:: rst .. code-block:: python import this リスト ====== バレットリスト、数字付きリスト、定義リストが利用できます。 .. code-block:: rst * 宇都宮市 * 那須塩原市 * 真岡市 1. まさし 2. みんみん #. 夢餃子(#を使うと、自動で数字が割り当てられます) 餃子 宇都宮の名物として有名。餃子の像もある。静岡の浜松がライバル。 ジャズ 宇都宮はジャズの町としても売り出し中。 楽器メーカーを多数抱える静岡の浜松がライバル 焼きそば 知る人ぞ知る宇都宮の名物。専門店多数。なぜかビニール袋で持ち帰る。 テーブル ======== テーブルの作成方法は様々な方法があります。 一番複雑な方法 -------------- 縦横のセルの連結も表現できます。 .. code-block:: rst +---------------------+ |栃木県内の勉強会 | +========+============+ |宇都宮 |集合知勉強会| + +------------+ | |Objective-C | +--------+------------+ |西那須野|とちぎRuby | +--------+------------+ 二番目に複雑な方法 ------------------ .. code-block:: rst =========== ================================== 勉強会で使う本 ---------------------------------------------- 言語 本の名前 =========== ================================== Ruby dRubyによる分散・Webプログラミング Python 集合知プログラミング Objective-C 詳解Objective-C 2.0 =========== ================================== これ以外にもディレクティブを使った方法がいくつかあります。詳細は :ref:`directives` を参照してください。 ディレクティブ ============== Sphinxが利用しているreStructuredTextのもっとも特徴的な機能がディレクティブです。Pythonを利用して新しいディレクティブを作ることもでき、Sphinxの拡張性の高さの源となっています。 ディレクティブの種類は多岐に渡っていて、すべてを詳解するのは難しいので、ここでは3つだけ詳解します。 すべてのディレクティブは次のような構造をしています。 .. code-block:: rst .. ディレクティブ名:: オプション :引数: :パラメータ付き引数: パラメータ コンテンツ ディレクティブの種類によって、オプションや引数、コンテンツが指定できるかが異なります。 画像 ---- 画像ファイルを埋め込むには、 ``figure`` ディレクティブを利用します。 .. code-block:: rst .. figure:: ./img/background.png :scale: 50 :align: left :target: http://sphinx-users.jp/ 一行あけてここに書いたものがキャプションになります 索引 ---- ``index`` ディレクティブを設定していくと、索引を作ることができます。階層を持つ索引も表現できます。このディレクティブをセクションタイトル、表、画像などの前に置くことで、それらの要素に対してのリンクが作成されます。 ``pair`` と ``triple`` による複数エントリー作成が強力なので、これを使うと、効率よく情報量の豊富な索引を生成できます。 .. code-block:: rst .. index:: ベルモール .. index:: pair: 遊園地; 那須ハイランドパーク .. index: triple: うさぎや; チャット; お菓子 これをビルドすると、6つの索引のエントリーが作成されます。 最初のディレクティブは「ベルモール」という項目が1つだけ作られます。 次のディレクティブは、「遊園地→那須ハイランドパーク」と、「那須ハイランドパーク→遊園地」という、階層を持つエントリーが2つ作られます。 3つめのディレクティブは、「うさぎや→チャット,お菓子」「チャット→うさぎや,お菓子」「お菓子→チャット,お菓子」という3組のエントリーが作られます。 注釈 ---- 注釈などを作成するディレクティブもあります。 .. code-block:: rst .. note:: 注釈です .. warning:: 警告です！ これ以外にも様々な種類のディレクティブがあります。ドキュメントなどを参照して、さまざまな種類のディレクティブを使ってみてください。