ラベル Sphinx の投稿を表示しています。 すべての投稿を表示
ラベル Sphinx の投稿を表示しています。 すべての投稿を表示

2012年1月19日木曜日

Sphinxのバージョンアップをする

Sphinx1.1から1.1.2に上げた時のメモ。

Sphinxの最新版を手に入れる。PythonのこのページからDL出来るっぽい。

■事前にやる事
/usr/local/lib/python2.6/dist-packages/Sphinx-1.1-py2.6.egg/
の中にあるthemeとか加工したソースとかを待避させておく事。

■旧Verの削除と新Verのインストール
sudo rm -fr /usr/local/lib/python2.6/dist-packages/Sphinx-1.1-py2.6.egg
wget http://pypi.python.org/packages/2.6/S/Sphinx/Sphinx-1.1.2-py2.6.egg#md5=d35db7a8ee62dd55522bca523954baa9
sudo easy_install Sphinx-1.1.2-py2.6.egg
終わり。

2012年1月18日水曜日

今日のsphinxメモ

sudo vi /etc/apt/sources.list

deb http://ppa.launchpad.net/vineuser/ppa/ubuntu oneiric main
deb-src http://ppa.launchpad.net/vineuser/ppa/ubuntu oneiric main

sudo apt-key adv --keyserver keyserver.ubuntu.com --recv-keys 0C95CAFC

sudo add-apt-repository ppa:vineuser

sudo aptitude update

sudo apt-get install texlive texlive-base ptex-base ptex-bin dvipsk-ja xdvik-ja ptex-jisfonts gs-cjk-resource jmpost dvipdfmx texlive-math-extra okumura-clsfiles jbibtex-bin mendexk texlive-latex-extra nkf dvipng python-software-properties python-sphinx

2012年1月17日火曜日

SphinxでHTMLでもPDFでも見やすい文書を一発で作る

昨年の秋位から Sphinx を本格的に使ってきたので色々メモした事、やった事をまとめて見る。Whyの部分は後で拡充するかも。

後これは俺が買って考えた事なので、これよりいい方法とか知ってる方いたら是非に教えてください。マジで。ホントに。
尚Sphinxを使える用にして、PDFまで出力出来る様にする方法は Sphinxとrst2pdfの「domains」がないよエラー を参照してください。


■やらないといけない事
取り敢えずやらないといけない要件は以下の通り。
  1. HTMLはHTMLで見やすく。PDFはPDFで見やすく。
  2. PDFは各章に通し番号を振る。HTMLは振らない。
  3. PDFは見出し必須。しかし見出しに載せる深さは2番目まで
  4. 内容的に同一の文書を使い回す場所がある。
これに加えて、HTMLとPDFの両方を作る場合以下の問題もあった。(今はもう Sphinx とか rst2pdf 側で対応してるかもだけど。)
  • HTMLを重視する場合、toctreeを使えば1ページに見出しだけが全てそろうので目的のページを探しやすく移動しやすい
  • PDFの場合、toctree を使って書くと章の番号を振るのがおかしくなる。
  • toctree はリンクになってしまいリンク先のページは個別で評価、変換されるっぽいのでPDFの場合だと章段落の程度がおかしくなる
  • include を使えば多数のファイルをマージして(1ファイルにして)から評価変換される用なので章段落の程度がおかしくならない。しかしHTMLだと一個のHTMLが巨大化してしまい死ぬほど見にくい。
つまり toctree は HTML と相性が良く、include は PDF と相性が良い。


■HTMLとPDFとを分けて考える
という事で「HTML用のRootドキュメントとPDF用のRootドキュメントを分ければいいんじゃね?」と考えて、調べてみたら出来るっぽい。Sphinxの conf.py の以下の場所の「indexPdf」の部分を変更する。
pdf_documents = [ ('indexPdf', 'Manualタイトル', u'Manualタイトル', u'Author', 'manual'), ]
初期値だとHTMLのと同じ奴に設定されてるけど、ここを変更するとPDFを作成する際はここで指定されたファイルをRootドキュメントにして作成してくれるようになる。こうしておけば make html pdf って一個のコマンドで違う構成ファイルを元にしたHTMLとPDFとが同時に作れる様になる。


■RSTファイルの構成
次に実際に利用するRSTファイル群は以下の様な構成に成っている。
  • index.rst ・・・ HTML用のドキュメント構成。ページ構成のRSTファイルを toctree で記述。
  • indexPdf.rst ・・・ PDF用のドキュメント構成ページ構成のRSTファイルを include で記述。
  • page.rst ・・・ 章構成。実コンテンツの本体。基本的に重複のない文書を書く。HTML用もPDF用も共通。 paragraph.rst を全て include で記述。 
  • paragraph.rst ・・・ 各パラグラフ。使い回す可能性のある文書はここに書いている。HTML用もPDF用も共通
index.rstは以下の通り
########
各章タイトル
########


.. toctree::
:maxdepth: 1


hoge
fuga
pugya
homu
indexPdf.rstは以下の通り。PDFの場合、各章の頭に数字を振りたいのでそのコマンドを先頭に入れておく。
.. section-numbering::


########
各章タイトル
########


.. include:: hoge.rst
.. include:: fuga.rst
.. include:: pugya.rst
.. include:: homu.rst
Sphinx公式のセクション管理 にSphinxでのセクション管理の例が載っているけど、私は以下の様なルールでセクションを利用している。
ただしpage.rstに関してはかなり流動的。使い回す可能性のない説明であれば、一番したのパラグラフまで使う事もある。
  • # 部: オーバーライン付き ・・・ index.rst/indexPdf .rst で使用
  • * 章: オーバーライン付き ・・・ page .rst で使用
  • =, セクション  ・・・ page .rst、 paragraph.rst で使用
  • -, サブセクション  ・・・   paragraph .rst で使用
  • ^, サブサブセクション  ・・・   paragraph.rst で使用
  • ", パラグラフ  ・・・   paragraph.rst で使用


■ PDFでの改ページ処理
一応rst2pdfには自動改ページ設定機能があるがこれが結構微妙。ルール一辺倒なのでいやここは・・・って所でも改ページしてしまう。なのでこれを使わず、面倒だけど自分で改ページを指定する事にした。

まずconf.pyの以下の設定をコメントアウトして自動改ページを無効にする。
#pdf_break_level = 2
で代わりの改ページ指定は、改ページしたい所に以下の記述を加えておく。これを入れておくとHTMLの方では何も出力されない。だけどPDFを出力する時のみ改ページ処理が行われる。
.. raw:: pdf


PageBreak
なお私が作ったドキュメントではこのPDF用改ページコマンドをpage.rstに末尾に必ず追加している。


■DPFの目次管理
次にPDFでのページ管理。toctreeを使うと目次っぽいのが勝手に出来るけど、includeを使うとそれが生成されない。なので rst2pdf の機能を使って目次を生成する。
また目次を設定する際、上から2番目(1.1 インストール方法)までを目次に載せるように設定する。これを指定しないと全てのセクションが目次に載ってしまう。(例えば 1.2.3.4.5 注意 とか)。
その為に conf.py に以下の設定を追加する。
pdf_use_toc = True
pdf_toc_depth = 2
目次に載せるセクションの深さは数字で自由に変更出来ます。


■ただ一つの欠点
これでHTMLとPDFの両方が見やすくなったと思う。
ただ唯一新しい章を追加する際にindex、indexPdfの2つに記述しないといけない事が面倒だけど。

参考になるURL

2011年8月5日金曜日

Sphinxとrst2pdfの「domains」がないよエラー

■環境
Ubuntu 9.10
Python 2.6.4
Sphinx 1.07
rst2pdf 0.16
sudo aptitude install build-essential python-setuptools python-sphinx python2.6-dev texlive-full
sudo easy_install -UZ PIL
sudo easy_install -UZ reportlab
sudo easy_install rst2pdf

でSphinxのドキュメントをPDFにしようとすると次のエラーがでる。
AttributeError: BuildEnvironment instance has no attribute 'domains'
そんな値ねーよ!って怒られる。
色々調べてみたけど、どうしてもコレが解決しなかったのでrst2pdfの最新ソースみてみた。

pdfbuilder.py

これの227行目。
if indices_config and hasattr(self.env, 'domains'):
超ドストレートな修正が入ってた(;゚Д゚)

という分けでソースを直に編集する。
sudo vi /usr/local/lib/python2.6/dist-packages/rst2pdf-0.16-py2.6.egg/rst2pdf/pdfbuilder.py

OK、通った。

で続いて
too many values to unpack
というエラーが出るのでこれに対処する。設定ファイルであるja.jsonを編集する

"embeddedFonts" :
[[
"VL-Gothic-Regular.ttf",
"VL-PGothic-Regular.ttf",
"ipam.ttf",
"ipag.ttf",
"ipagp.ttf", ←削除する
"ipamp.ttf" ←削除する
]],
とするとこのエラーは消える。

次は
[ERROR] pdfbuilder.py:129 FragLine instance has no attribute 'lineBreak'
というエラー。これもソースコードが問題っぽい。

これもソースコード修正すれば行けるっぽい
sudo vi /usr/local/lib/python2.6/dist-packages/reportlab-2.5-py2.6-linux-i686.egg/reportlab/platypus/paragraph.py
で335行目付近を以下の様に編集

# simple = last or abs(extraSpace)<=1e-8 or line.lineBreak ←オリジナル。コメントアウトする
simple = last or abs(extraSpace)<=1e-8 or getattr(line, 'lineBreak', False) ←追記する

でOK。 後Sphinxで使うCSSを編集したい場合は
/usr/share/sphinx/themes
/usr/local/lib/python2.6/dist-packages/Sphinx-1.1-py2.6.egg/sphinx/themes
以下にCSSがあるんでそれをいじる。或いはここに作った奴を配置する。 blockdiagを入れる。
sudo easy_install sphinxcontrib-blockdiag
でconf.pyに以下の2つを追加する。フォントはTrueTypeである必要有り
extensions = ['sphinxcontrib.blockdiag'] blockdiag_fontpath = '/usr/share/fonts/truetype/ipafont/ipagp.ttf'
以下の様に書けば図が出来る
.. blockdiag:: diagram admin { top_page -> config -> config_edit -> config_confirm -> top_page; }