ZONOTE: [sphinx]はじめにやることメモ

http://isann.blog2.fc2.com/blog-entry-290.html

http://isann.blog2.fc2.com/blog-entry-293.html

■sphinxって何？

ここ見たらだいたいわかります。
http://sphinx-users.jp/

わかってるからそう言うのでしょうか。
はじめはまったくわかりませんでした。

要は、テキストファイルにwiki記法みたいな簡易マークアックアップの「reStructredText」で
記述し、これをプログラムを使って綺麗なHTMLなどにする、ということです。

で、「reStructredText」はディレクティブというのがあって、
これを使ってブロック図を書いたりシーケンス図を書いたり、
「reStructredText」標準の機能に機能追加していく感じです。

Sphinxというとpython、
という感じですがpythonを知らないとsphinxを使えないことはまったくありません。

知らないといけないのは、「reStructredText」の記述方法とSphinxの使い方です。

■sphinxインストール

ではさっそくインストールします。
pythonのインストールはexeキックするだけです。
easy_installはこのへんを参考にして下さい。

http://sphinx-users.jp/gettingstarted/install_windows.html

easy-install sphinx

これだけです。

■プロジェクトを作る

sphinx-quickstart

質問には全部デフォルトで答えました。

以下だけ入力します。

プロジェクト名

バージョン番号

著者の名前

■diagインストール

http://blockdiag.com/ja/blockdiag/introduction.html#id2

easy_install pillow
easy_install blockdiag

■sphinxにdiagを埋め込む

上記だけでsphinxでblockdiagを使えるわけじゃなく、
上記はテキストファイル「diag」などからpng形式の画像データを作成するものです。
埋め込むには「sphinxcontrib-blockdiag」が必要です。

easy_install sphinxcontrib-blockdiag

■confの設定

./sphinx-project/conf.py
# Enabled extensions
extensions = ['sphinxcontrib.blockdiag']

# Fontpath for blockdiag (truetype font)
blockdiag_fontpath = 'C:\Windows\Fonts\msgothic.ttc'

ちょっとpythonファイルに設定を追記します。
pythonファイルもただのテキストファイルです。

■ディレクティブ

.. blockdiag:: [diag-filename]

例えばこんな感じで使えるようになります。

■トライアンドエラー的な…

blockdiagのpngファイルで日本語が文字化け

これは文字化け、なんだけれど要はデフォルトでは日本語フォント使ってなくて、
変なUTF-8の文字見つかったけどなににしたらわからーん！って状態。
```
rem set /P font=フォントのパスを指定して下さい。（日本語フォントがよい）：
set font="C:\Windows\Fonts\msgothic.ttc"
set /P diag=diagファイルのパスを指定して下さい。：
blockdiag -f %font% %diag%
pause
```
こうやって日本語フォント指定してやればいける。
でもちょっとノード内のフォントが上きれるんだよな…。これ原因不明です。

Sphinxのドキュメントで日本語が文字化け

これも上と同じような問題。
結局CSSのfont-familyの記述によって読み込まれているフォントが日本語非対応のフォントということらしい。

http://blog1.erp2py.com/2012/01/sphinx.html
＜転載＞

[Pythonフォルダ]　→　[Lib]　→　[site-packages]　→　[Sphinx-1.1.2-py2.7.egg]　→　[sphinx]
sphinxdoc.css_t ファイルをコピー＆ペーストする

[sphinx]　→　[themes]　→　[sphinxdoc]　→　[static] フォルダーに sphinxdoc.css_t ファイルがあるのでコピーして、ドキュメントの [_static] フォルダに貼り付ける。

ペーストした sphinxdoc.css_t ファイルをテキストエディタで開き、font-family を変更する。

sphinxdoc.css_t には font-family の指定が4カ所あるので変更する。私は次のように変更した。

bodyタグ指定、viewcode-backクラス指定

変更前
font-family: 'Lucida Grande', 'Lucida Sans Unicode', 'Geneva',
             'Verdana', sans-serif;
変更後
font-family: 'Arial', 'Helvetica', sans-serif;

cite, code, ttタグ指定、preタグ指定

変更前
font-family: 'Consolas', 'Deja Vu Sans Mono',
             'Bitstream Vera Sans Mono', monospace;
変更後
font-family: 'Consolas', 'Courier New', monospace;
make html コマンドで、htmlファイルを再作成する。

Lucida Grandeとか悪さをしているみたいです。>

■shpinxインストールの補足的な

Sphinxの導入は下記あたりで記事にしました。
http://isann.blog2.fc2.com/blog-entry-290.html
http://isann.blog2.fc2.com/blog-entry-292.html

これにわかったことなどを追加しながら少し整理してみます。

sphinxのインストールに関してはhttp://isann.blog2.fc2.com/blog-entry-290.htmlそのままです。
pypiに登録されていますので、easy_installから簡単にインストールして、
そのままプロジェクトを作ります。
sphinx-quickstart コマンドはデフォルトで実行したディレクトリ配下にファイルを作成しますので、
自分で /usr/hoge/shpinx_doc/hogedoc みたいなディレクトリを作成してそこで実行するとよいと思います。

diagシリーズはブロック図は汎用性もあるのであるとかなりいいと思います。

easy_install sphinxcontrib-blockdiag

これに追加でシーケンス図を僕はよく使うので入れています。
easy_install sphinxcontrib-seqdiag

http://blockdiag.com/ja/seqdiag/sphinxcontrib.html

他にもアクティビティ図やネットワーク図などがあります。
必要に応じて追加するといいかもです。
はじめに全部入れておいても不都合はないと思います。
http://d.hatena.ne.jp/torutk/20110522/p1
http://d.hatena.ne.jp/hekyou/20110717/p1

shpinxドキュメントにこれらの図を埋め込むにはconf.pyを設定する必要があります。
この時点で下記リンク先のようなconf.pyになっていました。
https://gist.github.com/1978985

extensions = []
extensions.append('sphinxcontrib.blockdiag')
extensions.append('sphinxcontrib.seqdiag')
extensions.append('japanesesupport')
blockdiag_fontpath = r'C:\Windows\Fonts\msgothic.ttc'
seqdiag_fontpath = r'C:\Windows\Fonts\msgothic.ttc'

extensions.append('XXXXX')
こんな感じでどんどん拡張を追加していくとやりやすいかもです。

あと、日付フォーマットは

today_fmt = '%Y-%m-%d %H:%M:%S'

にしました。

sphinxドキュメントをHTML出力する際に日本語が含まれると思いますので、
下記のようなパスにあるsphinxdoc.css_tを
C:\TracLight\python\Lib\site-packages\Sphinx-1.1.2-py2.6.egg\sphinx\themes\sphinxdoc\static\sphinxdoc.css_t
↓
F:\sphinxdoc\hoge\_static\sphinxdoc.css_t
みたいな感じでコピーしておきます。
https://gist.github.com/1978951

    font-family: 'Arial', 'Helvetica', sans-serif;
    ・
    font-family: 'Consolas', 'Courier New', monospace;
    ・
    font-family: 'Consolas', 'Courier New', monospace;
    ・
    font-family: 'Arial', 'Helvetica', sans-serif;

こんな順番で参考にさせて頂いたサイトと同様にfont-familyを変更しました。

シーケンス図の埋め込みはこんな感じです。

.. seqdiag::

    seqdiag admin {

      browser  -> webserver [label = "GET /index.html"];
      browser <-- webserver;
      browser  -> webserver [label = "POST /blog/comment"];
                  webserver  -> database [label = "INSERT comment"];
                  webserver <-- database;
      browser <-- webserver;
    
    }

ブロック図の埋め込みはこんな感じです。

.. blockdiag::

    blockdiag admin {
      
      // Set labels to nodes.
      A [label = "foo"];
      B [label = "bar"];
      // And set text-color
      C [label = "baz"];
   
      // Set labels to edges. (short text only)
      A -> B [label = "click bar", textcolor="red"];
      B -> C [label = "click baz"];
      C -> A;
   
    }

ブロック図に関してよく使うスタイルとか。

      node_width = 160;
      node_height = 60;
      default_fontsize = 12;
      default_node_color = "#4F81BD";
      default_textcolor = "#FFFFFF";
      class data [ shape = flowchart.input ];
      class ext_syori [color = "#9BBB59"];
      class ext_data [color = "#9BBB59", shape = flowchart.input];

あと、sphinxでテーブルの出力はまあまあ面倒くさくて、
list-tableやcsv-tableをよく使うことになる。
なんか癪だったのでpythonでtsvをうまくテーブルにするもの作ってみた。
https://gist.github.com/1977836
まだ、未完成でして、同一セル内の改行に対応できていません。

こんなところです。

ZONOTE

2012年11月2日金曜日

[sphinx]はじめにやることメモ