2. 外部機能

追加インストールで利用できる機能。PILが必要です。
blockdiag, seqdiag, actdiag, nwdiag を説明します。
これらは単体の画像生成コマンドラインツールとして提供されていて,それのSphinx用。

注釈

複雑な図では関係線が混ざってしまうなど破綻することがあります。そんな時はgraphvizを試してみてください。

4. Sphinx Extentions / より高度な表現

easy_install sphinxcontrib-blockdiag
easy_install sphinxcontrib-seqdiag
easy_install sphinxcontrib-actdiag
easy_install sphinxcontrib-nwdiag
conf.py に以下を追加。blockdiag_fontpath に日本語フォントを指定する(ttf)
フォントはリスト設定できるので各環境のフォントを列挙してOK.

注釈

インストールがうまくいかない時.

easy_install -U setuptools

yum reinstall sphinx

を試してみてください。

# Enabled extensions
extensions = [ 'sphinxcontrib.blockdiag','sphinxcontrib.seqdiag','sphinxcontrib.actdiag' ,'sphinxcontrib.nwdiag'  ]

# Fontpath for blockdiag (truetype font)
blockdiag_fontpath = ['ipagp.ttf']

2.1 ブロック図 (blockdiag:ブロックダイアグラム)

.. blockdiag::

        blockdiag {
                node_width = 200;
                node_height = 100;
                default_node_color = lightyellow;
                default_group_color = lightgreen;
                default_linecolor = magenta;
                default_textcolor = red;

                A -> B -> C;
                B -> D;
                group {
                    C; D;
                }
        }

2.2 シーケンス図生成ツール seqdiag

Name Description
A first node
B second node
C third node
.. seqdiag::
   :desctable:

   seqdiag {
      A -> B -> C;
      A [description = "first node"];
      B [description = "second node"];
      C [description = "third node"];
   }

2.3 アクティビティ図生成ツール actdiag

Name Description
A first action
B second action
C third action
.. actdiag::
   :desctable:

   actdiag {
      A -> B -> C;
      A [description = "first action"];
      B [description = "second action"];
      C [description = "third action"];

      lane {
         A; B;
      }
      lane {
         C;
      }
   }

2.4 ネットワーク図生成ツール nwdiag

Name Description
A web server01
B web server02
C database server
.. nwdiag::
   :desctable:

   nwdiag {
      network {
        A [address = 192.168.0.1, description = "web server01"];
        B [address = 192.168.0.2, description = "web server02"];
      }
      network {
        A [address = 172.0.0.1];
        C [address = 172.0.0.2, description = "database server"];
      }
   }

2.5 pandoc で markdown (書きかけ)

** うまく動かないので検証中 *

reStructuredTextは高機能ですが 普段は markdown記法のほうが早くてサクサク書けて便利という場面もあるでしょう。

pandoc を使うと sphinx でも markdown記法が利用できます。 まずはインストール

linux)

$ sudo apt-get install pandoc

windows&mac )

このサイトからインストーラーをダウンロードできます。

https://code.google.com/p/pandoc/downloads/list

sphinxcontrib_markdownのインストール

コレを使うと pandoc 利用が簡単に出来るらしい、のですが動きません。これ以下の文書含め検証中。。。

https://gist.github.com/tk0miya/4336929

conf.py 以下の内容を追記

# 以下の内容を追記
sys.path += ["."]
extensions += ["markdown"]

markdown_title = 'hello world'
source_suffix = '.md    PROJECT_DIR = os.path.dirname(__file__)

markdown でドキュメントを作るツールは mkdocs など他にあるのでそっちを利用するほうがいいのかも?

(markdown document processor) http://www.mkdocs.org/

(こんな記事もあったけどうまく動かず) https://mistymagich.wordpress.com/2014/03/18/sphinx%E3%82%92markdown%E3%82%92%E4%BD%BF%E3%81%A3%E3%81%A6%E8%A8%98%E8%BF%B0%E3%81%99%E3%82%8B/

(付録)markdown

ここがわかりやすいです

http://kojika17.com/2013/01/starting-markdown.html

(見出し)

# 見出し h1

## 見出し h2

### 見出し h3

**string**  で強調

(リスト)

* 色は匂へど
* 散りぬるを
* 我が世誰ぞ
  - 常ならむ
  - 有為の奥山
* 今日越えて  (半角スペースを2つ)
浅き夢見じ
+ 酔ひもせず

(罫線)

3つ以上の*(アスタリスク), -(ハイフン), _(アンダースコア)と半角スペースのみの行は、罫線として扱われます。

Markdown

***

* * *

*****

- - -

---------------------------------------

___

(リンク)

角括弧で文言、丸括弧でURLを囲むと、リンクになります。

[ローカルホスト](http://localhost)


(linkを変数的に扱う例)
I get 10 times more traffic from [Google] [1] than from
[Yahoo] [2] or [MSN] [3].

  [1]: http://google.com/        "Google"
  [2]: http://search.yahoo.com/  "Yahoo Search"
  [3]: http://search.msn.com/    "MSN Search"

3. そのほか機能

3.1 todo

Todo機能を付加します。
自分の備忘録として文中埋め込みをする以外に、共同作業のコメントやフィードバックにも便利な機能。
(conf.py)
# sphinx.ext.todo モジュールを読み込む
extensions += ['sphinx.ext.todo']

# ToDo 項目を表示する (デフォルトは表示しない; False)
todo_include_todos = True
(code)
.. todo:: この記事は書きかけ

課題

この記事は書きかけ

todo list の表示も設定可能。

.. todolist::

(todolist の表示↓)

3.1.1 todo list

課題

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

(元のエントリ は、 /home/wataru/DTI2/sphinx/sphinx_man/source/part_1.rst の 218 行目です)

(元のエントリ は、 /home/wataru/DTI2/sphinx/sphinx_man/source/part_1.rst の 412 行目です)

課題

この記事は書きかけ

(元のエントリ は、 /home/wataru/DTI2/sphinx/sphinx_man/source/part_2.rst の 353 行目です)

課題

この記事は書きかけ

(元のエントリ は、 /home/wataru/DTI2/sphinx/sphinx_man/source/part_2.rst の 375 行目です)

課題

この記事は書きかけ

(元のエントリ は、 /home/wataru/DTI2/sphinx/sphinx_man/source/part_2.rst の 388 行目です)

課題

この部分調査中

(元のエントリ は、 /home/wataru/DTI2/sphinx/sphinx_man/source/part_2.rst の 681 行目です)

課題

size=0のファイルが生成されて正しく動かないので後回し

(元のエントリ は、 /home/wataru/DTI2/sphinx/sphinx_man/source/part_2.rst の 706 行目です)

3.2 googlechart extension

課題

この記事は書きかけ

インストール

easy_install sphinxcontrib-googlechart

3.3 google analystics extension

課題

この記事は書きかけ

インストール

easy_install sphinxcontrib-googleanalytics

conf.py

# sphinxcontrib.googleanalytics モジュールを読み込む
extensions += ['sphinxcontrib.googleanalytics']

# GoogleAnalytics の ID
googleanalytics_id = 'UA-xxxxxxxx-1'

3.4 theme

デフォルトのtheme以外も設定可能です。

インストール

easy_install sphinxjp.themes.basicstrap
easy_install sphinxjp.themes.bizstyle

conf.py

extensions += ['sphinxjp.themecore']
html_theme = 'bizstyle'

4. Sphinx Extentions / より高度な表現

4.1 graphviz

フローなどのグラフを表示する機能。イストールは少々複雑。

4.1.1 graphviz のインストール

インストールをした上で、実行ファイルのあるフォルダにパスを通します。

  1. windows版 graphiviz のインストール

  2. path を設定

C:\Program Files (x86)\Graphviz2.38\bin


(3) sphinx graphviz インストール
conf.py にモジュールを追加します
extensions += ['sphinx.ext.graphviz']

4.1.2 graphviz のコーディング

例1 digraph

digraph は矢印で連結される図で、ノードを -> でつなぎます。

digraph foo {
   "bar" -> "baz";
}

.. graphviz::

   digraph foo {
      "bar" -> "baz";
   }

例2 graph

graph は線で連結される図で、ノードを – でつなぎます。

graph foo {
   "bar" -- "baz";
}

.. graphviz::

   graph foo {
      "bar" -- "baz";
   }

例3 簡易的な書き方

digraph foo {
"bar" -> "baz" -> "quux";
}

.. digraph:: foo

   "bar" -> "baz" -> "quux";

例4 ちょっと複雑

graph askeet{
        node[shape = circle];
        edge[arrowhead = dot, headlabel = n, taillabel = 1];
        "question"[width = 1];
        "answer"[width = 2];
        "user"[width = 1];
        "interest"[color = "blue"];
        "relevancy"[color = "blue"];
        "question" -- "answer"[style = dotted];
        "question" -- "interest";
        "answer" -- "relevancy"
        "user" -- "question"[style = dotted];
        "user" -- "answer"[style = dotted];
        "user" -- "interest";
        "user" -- "relevancy";
}

.. graphviz::

        graph askeet{
                node[shape = circle];
                edge[arrowhead = dot, headlabel = n, taillabel = 1];
                "question"[width = 1];
                "answer"[width = 2];
                "user"[width = 1];
                "interest"[color = "blue"];
                "relevancy"[color = "blue"];
                "question" -- "answer"[style = dotted];
                "question" -- "interest";
                "answer" -- "relevancy"
                "user" -- "question"[style = dotted];
                "user" -- "answer"[style = dotted];
                "user" -- "interest";
                "user" -- "relevancy";
        }

shape で描画する図形を変えることができます。(以下のURLを参照)

http://www.graphviz.org/doc/info/shapes.html

4.1.3 書き方の基本

使い始めでほしくなる機能をいくつか紹介します。

デフォルトの値を設定するオブジェクトとして、

-graph

-node

-edge

の3つがあります。graph は図の設定、 node はノードの初期値、 edge は矢印の初期値です。

日本語の名前で青色で描画したノードを作る例。日本語フォントの指定をする必要があります。

graph boy_and_girl {
        boy1[ label="太郎", fontname="MS UI Gothic", style=filled, fillcolor="skyblue" ];
        girl1[ label="花子", fontname="MS UI Gothic", style=filled, fillcolor="pink" ];
        boy1 -- girl1;
}

.. graphviz::

        graph boy_and_girl {
                boy1[ label="太郎", fontname="MS UI Gothic", style=filled, fillcolor="skypblue" ];
                girl1[ label="花子", fontname="MS UI Gothic", style=filled, fillcolor="pink" ];
                boy1 -- girl1;
        }

毎回、フォント指定などを描くのは大変なので node で初期値を指定します。

また図そのものの属性は graph で設定します。

例では node や edge の初期値 を指定して見た目を変えてみました。

digraph boy_and_girl {
        rankdir = LR
        graph [ label = "ドラえもんはどこだ?", fontname="MS UI Gothic",  bgcolor = "#e0e0e0"  ]
        node [ fontname="MS UI Gothic", style=filled, shape = circle ];
        edge[ penwidth=4, color="green", dir = both ]
        boy1[ label="のび太",  fillcolor="skyblue" ];
        girl1[ label="しずか",  fillcolor="pink" , shape=doublecircle ];
        boy1 -> girl1;
}

デフォルトでは上から下へ作られますが rankdir=LR で 左から右へ、となります。

また、 graph[] を設定することで図に名前を付けることが出来ます。

.. graphviz::

        digraph boy_and_girl {
                rankdir = LR
                graph [ label = "ドラえもんはどこだ?", fontname="MS UI Gothic",  bgcolor = "#e0e0e0" ]
                edge[ penwidth=4, color="green", dir = both ]
                node [ fontname="MS UI Gothic", style=filled ,shape = component ];
                boy1[ label="のび太",  fillcolor="skyblue" ];
                girl1[ label="しずか",  fillcolor="pink" , shape=doublecircle];
                boy1 -> girl1[arrowtail = solid];
        }

4.2 PlantUML

あらかじめJAVAのインストールとパス設定が必要そう。 (調査中)

4.2.1 インストール

4.2.1.1 JAVAのインストール

Java JRE (Java Runtime Environment) or JDK (Java Development Toolkit) がインストールされていること

http://java.com/ja/download/

4.2.1.2 palntuml.jar のインストール

$ sudo apt-get install openjdk-6-jre
$ wget 'http://downloads.sourceforge.net/project/plantuml/plantuml.jar'

windowsの場合

http://plantuml.sourceforge.net/download.html

課題

この部分調査中

4.2.1.3 sphinx用モジュールのインストール

easy_install sphinxcontrib-plantuml
conf.py にモジュールを追加します
extensions += ['sphinxcontrib.plantuml']

# PlantUML の起動方法を設定する
plantuml = ['java', '-jar', '/path/to/plantuml.jar']

4.2.2 サンプル

課題

size=0のファイルが生成されて正しく動かないので後回し

.. uml::

   Alice -> Bob: Hi!
   Alice <- Bob: How are you?

.. uml::

   class "This is my class" as class1 {
      +myMethods()
      -myMethods2()
      String name
   }
   class class2 as "It works this way too" <<Serializable>> {
      String name
   }
   class2 *-- "foo/dummy" : use

5. PDF 出力

5.1.1 TeXLiveのインストール

SphinxからPDFファイルを作成する場合、rst2pdfとLatex経由の2種類ありますが、Latex経由のほうが見た目がきれいなPDFファイルが作れるようなので、こちらの方法をとります。

Installing TeX Live over the Internetから「install-tl.zip」をダウンロードします

(現在、インストーラー install-tl-windows.exe があります。 インストールにはかなり時間がかかります。)

※インストール後、自動で実行ファイル位置のパスを通してくれます。

5.1.2 Sphinxの設定

(conf.py)

# 言語の設定
language = 'ja'
# LaTeX の docclass 設定
latex_docclass = {'manual': 'jsbook'}

を設定後、

make latexpdfja

とするだけす。

Windowsの場合は

C:Python27Libsite-packagessphinx

に 下記の _static/make.bat をおく。

※platex, extractbb を外部コマンドとして要求されます。

5.1.3 注意点

blockdiag系で日本語を使っていると、文字コードエラーで落ちる場合、

  1. conf.py の blockdiag_fontpath
blockdiag_fontpath = []

に正しくフォントが設定されているか確認してください。

  1. latex_elements の確認

http://bmath.org/wordpress/?author=1

conf.py)
latex_elements = {
    'babel': '\\usepackage[japanese]{babel}',
    }

6. 検索機能と日本語環境

(以下、下記かけ。最新のWindows版 MeCab でutf-8化がうまくいかないため調査中)

Sphinxの検索は自動作成される html/searchindex.js で処理されるが日本語だとうまく動かないので追加の環境設定を行う。

6.1 MeCAB インストール

Windowsは↓からダウンロードしてインストール。インストール時にUTF-8を選択すること。

http://mecab.googlecode.com/svn/trunk/mecab/doc/index.html

設定ファイルの編集

conf.py)
html_search_laguage = 'ja'
html_search_options = {'type':'mecab'}

辞書ファイルのUTF-8化

UTF-8でインストールしても辞書はsjisのままのようです。(笑

C:Program Files (x86)MeCabdic

http://nymemo.com/mecab/502/

2.2 検索の向上

Quick search の検索からヒットしないことが多いので調べてみたのでメモ。

  • mySqlなどを使う方法
  • mecabの辞書に単語を追加する方法
  • search.js をハック

などがあるがどれもお手軽でないので引き続き調査中。