_images/sphinx-logo.png

はじめに

Sphinxの使い方はユーザー会 http://sphinx-users.jp/ に詳しい情報があります。

以下、初めて入門する人向けに基本的なマークアップを解説します。 書き始めるときに必ず必要な記述方法や、よく使うマークアップを集めました。 他にもたくさんの機能があるので必要に応じて検索などで調べてみてください。

1. Sphinx はじめのいっぽ

以下のコマンドでプロジェクトを作成し、*.rst というドキュメントファイルを追加して記述をします。

sphinx-quickstart

HTMLの自動作成は、make コマンド

make html

他にも引数の指定で別のフォーマットの文書を作成出来ます。

make latexpdfja

1.1. セクション

Sphinx は主にセクションとインデントで文書をの構造を構成します。 セクションは部や章などのタイトル/区切りです。通常の文章を書くならこれだけ覚えるのでも 十分見やすい文章を作ることが出来、自動で目次も作れてしまいます。

書き方

特定の文字によるアンダーラインがあるとき、”セクション”と判定して見出しのレベルが変わります。慣例として以下の文字を使います。

セクション判定文字の例
文字 解説
#
*
= セクション
- サブセクション
^ サブサブセクション
ダブルクオート パラグラフ

として使います。

※体裁が崩れるため、別のドキュメントに例を書きました。下記のリンク先をご確認ください。

セクションの例

1.2 インデント

スペースやタブでインデントをつけられます。

1行目

2行目 3行目

4行目
5行目 6行目 7行目

※上記の表示は以下のような記述になります。 | インデントごは改行がないと前の行の末尾から続いて表示されます。(通常の表示ルールと同じ) | 改行には後述の ‘ | ‘を使います。

1行目
        2行目
        3行目

        4行目
                5行目
                6行目
                7行目

1.3 セパレーター/水平線

セクションで使える記号を4つ以上並べた行を書くと水平線が引けます。

段落1

----

段落2

++++

段落3

適用例:

段落1

段落2

段落3

1.3. 強調 (インラインマークアップ)

強調 文字列 *で囲む <em>
強い強調 文字列 **で囲む <strong>
from PIL import PIL コード文字列 ``で囲む <span class=”pre”>
(コード)
======================== =============== =============== ===============================
*強調*                    文字列         *で囲む         <em>
**強い強調**              文字列         **で囲む        <strong>
`from PIL import PIL`     コード文字列   ``で囲む        <span class=”pre”>
======================== =============== =============== ===============================

1.4. 引用

1.4.1 改行なしの引用 以下は引用文です

おはよう こんにちは こんばんは

(ここは引用の外です)

(コード)
以下は引用文です。
    おはよう
    こんにちは
    こんばんは
(ここは引用の外です)

1.4.2 改行ありの引用

‘|’ を入れると改行されます。

例)以下の行は、 ソースファイルと同じように改行されます。
インデントの後は
スペース入れてください。
改行されます。

※’|’の後にスペースが必要なので注意!

(コード)
 | 例)以下の行は、 ソースファイルと同じように改行されます。

         | インデントの後は
         | スペース入れてください。
         | 改行されます。

課題

うまく改行のコントロールが出来ないのでコツを調査中

1.5. 番号なしリスト

*、+、-を使って項目を並べるとリストになります。

  • 項目1
  • 項目2
  • 項目3
  • 項目1
  • 項目2
  • 項目3
(コード)
* 項目1
* 項目2
* 項目3

+ 項目1
+ 項目2
- 項目3

1.6. 番号付きリスト

  1. 項目1
  2. 項目2
  3. 項目3
  4. 項目1
  5. 項目2
  6. 項目3
(コード)
1. 項目1
2. 項目2
3. 項目3

#. 項目1
#. 項目2
#. 項目3

1.7. コードブロック

プログラムコードなどを表示するハイライト表示付のブロックです。

※”.. code ... “のあとに一行空行が必要です。

#pythonのコード
import sys
print sys.path
.. code-block:: python

        #pythonのコード
        import sys
        print sys.path

pygments.py というサービスを使っていて、多くの言語に対応しています。

Programming languages

ActionScript Ada ANTLR AppleScript Assembly (various) Asymptote Befunge Boo BrainFuck C, C++ C# Clojure CoffeeScript ColdFusion Common Lisp Cython D Delphi Dylan Erlang Fortran Gherkin (Cucumber) GL shaders Haskell (incl. Literate Haskell) Io Java JavaScript LLVM Logtalk Lua Matlab MiniD Modelica Modula-2 MuPad Objective-C Objective-J OCaml PHP Perl PovRay Prolog Python 2.x and 3.x (incl. console sessions and tracebacks) Rebol Redcode Ruby (incl. irb sessions) S, S-Plus, R Scala Scheme Smalltalk Tcl Vala Visual Basic.NET XQuery

Template languages

Cheetah templates Django/Jinja templates ERB (Ruby templating) Genshi (the Trac template language) JSP (Java Server Pages) Myghty (the HTML::Mason based framework) Mako (the Myghty successor) Smarty templates (PHP templating)

Other markup

Apache config files Bash shell scripts BBCode CMake CSS Debian control files Diff files Gettext catalogs Gnuplot script Groff markup HTML INI-style config files IRC logs (irssi style) Lighttpd config files Makefiles MoinMoin/Trac Wiki markup MySQL Nginx config files POV-Ray scenes Ragel Redcode ReST SQL, also MySQL, SQLite Squid configuration TeX tcsh Vim Script Windows batch files XML XSLT YAML
//C言語

printf( "hello world" );
exit(0);
.. code-block:: c

        //C言語
        printf( "hello world" );
        exit(0);

1.8 連結機能

1.8.1 ラベルと参照

ラベルへのリファレンス(ジャンプタグ) ※ ‘_’(アンダースコア)付のラベル名にすること。

(例) (test)1章 (test)2章 を参照してください。

(test)1章

brabrabara..... (end of chapter 1)

(test)2章

brabrabara..... (end of chapter 2)
(コード)
:ref:`label_chap1`
:ref:`label_chap2` を参照してください。

.. _label_chap1:

1章
-----
    brabrabara..... (end of chapter 1)

.. _label_chap2:

2章
-----
    brabrabara..... (end of chapter 2)

1.8.2 他のドキュメントへの参照

他のドキュメントへのリファレンス(ジャンプタグ)

1st
(コード)
:doc:`1st`

1.8.3 リンク

`???<URL>`_ と記述します。_を忘れないように!

`(C) Initerio, Inc. <http://www.interio-inc.com>`_
結果:
(C) Initerio, Inc.
(コード)
* http://sphinx-doc.org/
* `github <https://github.com>`_
* Sphinx-users.jp_
.. _Sphinx-users.jp: http://sphinx-users.jp/

1.8.4 索引

indexディレクティブを設定することで、索引を作ることができます。

1.8.5 ダウンロード用のリンク

part_2.rst

(コード)
:download:`part_2.rst`

1.8.6 用語 term

定義された用語の定義ドキュメント位置にジャンプするリファレンス(ジャンプタグ)。 用語の定義は glossary ディレクティブを使用して定義します。glossary.rst など別に作ると良いらしい。

glossary

ディレクティブ

(コード)
:term:`ディレクティブ`

1.8.7 glossary

用語の定義を行います。

.. glossary::

        glossary
                用語の定義リストを記述するディレクティブ

        term
                定義された用語の表示を変えるroleです

1.9. 画像

画像を埋め込む記法。

gambo.jpg
_images/gambo.jpg
yoso1.jpg
_images/balls.jpg
(コード)
| gambo.jpg
        .. image:: images/gambo.jpg
| yoso1.jpg
        .. figure:: images/balls.jpg

*image 記述のあとに表示サイズなどのアトリビュートを指定できます。

.. image:: images/gambo.jpg
        :scale: 40%
        :height: 100px
        :width: 200px
        :align: center
_images/gambo.jpg

※alignには配置指定”top”, “middle”, “bottom”, “left”, “center”, “right”が使える

1.10. テーブル

表形式のテーブルはそのまま書く方法とCSVデータから描画する方法があります。 | CSVテーブルは体裁の調節が楽なので便利です。

1.10.1. データテーブル1

col1 col2 col3
row1 a b
row2 a b
row3 a b
(コード)
===================== ==================== ====================
col1                   col2                 col3
===================== ==================== ====================
row1                   a                    b
row2                   a                    b
row3                   a                    b
===================== ==================== ====================

1.10.2 csv-table

CSVは直接データを書くか、ファイルで指定することが出来ます。

(詳しくはこちら) http://sphinx-users.jp/gettingstarted/directives.html

Frozen Delights!
Treat Quantity Description
Albatross 2.99 On a stick!
Crunchy Frog 1.49 If we took the bones out, it wouldn’t be crunchy, now would it?
Gannet Ripple 1.99 On a stick!
(コード)
.. csv-table:: Frozen Delights!
        :header: "Treat", "Quantity", "Description"
        :widths: 15, 10, 30

        "Albatross", 2.99, "On a stick!"
        "Crunchy Frog", 1.49, "If we took the bones out, it wouldn't be crunchy, now would it?"
        "Gannet Ripple", 1.99, "On a stick!"

1.10.3. list-table

Frozen Delights!
Treat
  • Quantity
  • Description
Albatross
  • 2.99
  • On a stick!
Crunchy Frog
  • 1.49
  • If we took the bones out, it wouldn’t be crunchy, now would it?
Gannet Ripple
  • 1.99
  • On a stick!

1.11. 注釈

ノート

注釈

これは注釈です!

(コード)
.. note::
        これは注釈です!

警告

警告

これは警告です!

(コード)
.. warning::
        これは警告です!