Sphinxとは

テキスト(reStructuredTextファイル)から各種フォーマット(HTML,ePub,Latex,pdf,docx)を作成できる。 pythonのドキュメント(http://docs.python.jp/2/)なんかもこのSphinxで作成されています。

メリット

業務での利用が増えているらしい(社内ではHTMLで共有,PDFに変換して納品といった流れ)
環境やエディタを選ばない。
ツールで自動生成しやすい
提出用pdf出力など,一つのソースから複数のフォーマットに出力できる。
目次(toctree)ベースで文書構造を作れる
バージョン管理できる
Jenkinsで変換,公開を自動化できる

まだ詳しくはわかっていないけど,かなり便利そうなのは間違いなさそう。早速導入してみます。

インストール(Mac OS X Mountain Lion)

Pythonにはeasy-installという、外部ライブラリをインストールするのに便利なコマンドがあるので,まずはそれをインストール。

http://peak.telecommunity.com/dist/ez_setup.py

↑のpython スクリプトを右クリックから保存。Terminalを開きpython スクリプトをダウンロードしたフォルダに移動し,スクリプトの実行。具体的には↓。

$ cd Downloads
$ python ez_setup.py

これでeasy_installがインストールできたので,次はそれを使用してSphinxのライブラリをインストール

$ easy_install sphinx

これでSphinxのインストール完了。sphinx-quickstartコマンドを実行すると対話モードで起動できる。終了するにはCtrl + c。

プロジェクトのひな形作成

とりあえず起動はsphinx-quickstartコマンド。するといくつかの質問をされる。質問の意味などは,こちら(ゼロからはじめるSphinx《入門編》 - 独学Linux)が参考になります。

$ mkdir sphinx
$ cd sphinx
$ sphinx-quickstart

・・・いろいろな質問に答える

$  ls
Makefile    build       make.bat    source

設定についてちゃんと知りたい方は,こちらsphinx-quickstartの詳細説明

htmlやpdfに出力する方法。

Sphinxのドキュメントにいけばサンプルドキュメントがのっています。基本的な書き方は,そちらプロジェクトを作るを見れば分かります。

ちなみにサンプルドキュメントの"expert_python.rst"や"art_of_community.rst"は,sourceフォルダの中に格納します。

HTMLに出力する方法

Makefileのあるディレクトリ上で,'make html'を実行する。

$ ls
Makefile    build       make.bat    source
$ make html

LaTeX経由でPDFに出力する方法

まずは,HTMLを出力した時と同じディレクトリに移動します。 PDFに直接出力する方法もあるようですが,LaTeX経由でPDF出力する方が簡単らしいのでそちらでやってみます。

$ make latex

これで、build/latexというフォルダ内にtexのソースファイルと独自のstyファイルが保存されます。続いて、このフォルダに移動してmakeします。

$ cd build/latex
$ make all-pdf-ja

rst2pdf拡張を使ってPDFに出力する方法

Sphinxはrst2pdfと連携することによりPDFを出力することも出来ます。参考にしたページは↓。

まずはこちらを参考にrst2pdfをインストール。

$ sudo easy_install rst2pdf

次はconf.py,Makefileを編集し,Makefileがある場所と同じところにja.jsonを作成。

conf.pyに↓を追記(こちらを参考)

extensions = ['rst2pdf.pdfbuilder']

# -- Options for PDF output --------------------------------------------------

# Grouping the document tree into PDF files. List of tuples
# (source start file, target name, title, author, options).
#
# If there is more than one author, separate them with \\.
# For example: r'Guido van Rossum\\Fred L. Drake, Jr., editor'
#
# The options element is a dictionary that lets you override
# this config per-document.
# For example,
# ('index', u'MyProject', u'My Project', u'Author Name',
#  dict(pdf_compressed = True))
# would mean that specific document would be compressed
# regardless of the global pdf_compressed setting.

pdf_documents = [
    ('index', u'MyProject', u'My Project', u'Author Name'),
]

# A comma-separated list of custom stylesheets. Example:
pdf_stylesheets = ['sphinx','kerning','a4','ja']

# Create a compressed PDF
# Use True/False or 1/0
# Example: compressed=True
#pdf_compressed = False

# A colon-separated list of folders to search for fonts. Example:
pdf_font_path = ['/usr/share/fonts']

# Language to be used for hyphenation support
pdf_language = "ja"

# Mode for literal blocks wider than the frame. Can be
# overflow, shrink or truncate
#pdf_fit_mode = "shrink"

# Section level that forces a break page.
# For example: 1 means top-level sections start in a new page
# 0 means disabled
#pdf_break_level = 0

# When a section starts in a new page, force it to be 'even', 'odd',
# or just use 'any'
#pdf_breakside = 'any'

# Insert footnotes where they are defined instead of
# at the end.
#pdf_inline_footnotes = True

# verbosity level. 0 1 or 2
#pdf_verbosity = 0

# If false, no index is generated.
#pdf_use_index = True

# If false, no modindex is generated.
#pdf_use_modindex = True

# If false, no coverpage is generated.
#pdf_use_coverpage = True

# Documents to append as an appendix to all manuals.
#pdf_appendices = []

# Enable experimental feature to split table cells. Use it
# if you get "DelayedTable too big" errors
#pdf_splittables = False

# Set the default DPI for images
#pdf_default_dpi = 72

Makefileに↓を追記(こちらを参考)

pdf:
    $(SPHINXBUILD) -b pdf $(ALLSPHINXOPTS) $(BUILDDIR)/pdf
    @echo
    @echo "Build finished. The PDF files are in _build/pdf."

ちなみにMakefileのインデントはタブでしないといけないようです。半角スペース4つだと↓のようにビルド出来ませんでした。

$ make pdf
Makefile:180: *** missing separator.  Stop.

ja.jsonをMakefileと同じところに作成。

{
        "styles" : [
                ["base" , {
                        "wordWrap": "CJK"
                }]
        ]
}

ここでmake pdfコマンドを実行すると,build/pdf/フォルダの中にPDFファイルが作成されます。

ePubに出力する方法

ePubもHTMLのように簡単です。

$ make epub

conf.pyの設定

ドキュメントを日本語にする(conf.pyの60行目)

language = None→language = 'ja'

テーマを変更する(conf.pyの102行目)

テーマについてはこちらが詳しいです。色々試してみた結果個人的にはhaikuというテーマがお気に入りです。

html_theme = 'default'→html_theme = 'haiku'

ドキュメントの基本的な書き方

ドキュメントの書き方は,↓のリンクを参考にしながら色々遊んでたらわかりました。結構分かりやすい書き方なのでLaTeXと違ってすぐに扱えました。

参考資料

Pythonプロフェッショナルプログラミング

作者: ビープラウド
出版社/メーカー: 秀和システム
発売日: 2012/03/26
メディア: 単行本
購入: 6人クリック: 765回
この商品を含むブログ (27件) を見る

c-bata web

テキストからHTMLやTeX,pdf,docxをつくれるSphinxがドキュメント作成にかなり便利だったのでメモ