2373801 ランダム
 ホーム | 日記 | プロフィール 【フォローする】 【ログイン】

傀儡師の館.Python

PR

日記/記事の投稿

カレンダー

キーワードサーチ

▼キーワード検索

カテゴリ

バックナンバー

2019年06月
2019年05月
2019年04月
2019年03月
2019年02月
2019年01月
2018年12月
2018年11月
2018年10月
2018年09月

フリーページ

プロフィール


kugutsushi

サイド自由欄

設定されていません。
2008年03月23日
XML
カテゴリ:Python
SPHINX: PYTHON DOCUMENTATION GENERATOR を見る。SPHINX は、Georg Brandl 氏によって作られた Python プロジェクトのドキュメントを生成してくれるプログラム。reStructuredText のソースを HTML、Windows HTML Help、LaTeX、PDF といった出力形式で出力してくれる。reStructuredText のパースは、Docutils を使っているようだ。元は、Python Documentation のために作られて、他でも使えるように、きれいに書き直されたもののようだ。

対象となるのは、基本的には手で書かれた reStructuredText で、ソースから API のドキュメントを生成するような用途としては、Epydoc の方が向いているようだ。

動作環境は Python 2.4 以降で、ソースコードの自動ハイライトに関しては Pygments ライブラリが使われているので、これもインストールする必要がある。当然、docutils も必要。どちらも、ソースコードから setup.py でインストールすることもできるし、easy_install でインストールすることもできる。最新のバージョンは、Sphinx 0.1.61611

インストールは easy_install を使えば、一発(docutils, sphinx, pygments)でインストールできる。

# easy_install sphinx

インストールしたら、

$ sphinx-quickstart

を実行すると、次々と質問されるので答えていくと、カレントディレクトリに Makefile と設定用ファイル conf.py と、サンプルの index.rst が作られる。これに加えて .build、.static、.templates も作られるが中身は空。sphinx-quicstart の実行中に最低限入力しなければいけないのは、"Project name", "Author name", "Project version"。それぞれ適当に入力する。その他は、とりあえずリターンで OK。

ちなみに、Separate source and build directories (y/n) で y と答えると、build 用のディレクトリ(build)とソース用のディレクトリ (source) が作られる。source ディレクトリの中には、サンプルの index.rst と、設定ファイルの conf.py が作られる。ソースと生成されたファイルは別ディレクトリの方がきれいかな(conf.py はドキュメントルートに作られるので、この場合は source に作られる)。

sphinx-quickstart で基本環境(Makefile 等)ができたら、次は、実際のドキュメントの生成。make をオプションなしに実行すると、何が指定できるのか分かる。

$ make
Please use `make <target>' where <target> is one of
html to make standalone HTML files
web to make files usable by Sphinx.web
htmlhelp to make HTML files and a HTML help project
latex to make LaTeX files, you can set PAPER=a4 or PAPER=letter
changes to make an overview over all changed/added/deprecated items
linkcheck to check all external links for integrity

とりあえず、

$ make html

とすると、.build/html にサンプルドキュメントが生成された。こんな感じで、なかなか色合い的にもかっこよくて見やすい。

sphinx.png

「make htmlhelp」とすれば、Windows Help 用のファイルを .build/htmlhelp に生成してくれるので、これをヘルプコンパイラでコンパイルするとヘルプファイルができる。あるいは、make latex で .build/latex に latex ファイルと Makefile 作られているのでさらに make all-pdf で pdf を生成することができる。

また、

$ sphinx-build.py -b latex sourcedir builddir

のようにコマンドラインから出力形式やソースやビルド用のオプションを指定することもできる。

html の生成は、.templates に自分用のテンプレートを用意してもいいが、テンプレートは、Jinja テンプレートエンジンを使っている。Django templates に触発されて作られたというもので、似たような文法になっているらしい。

ちなみに Sphinx では標準の reStructuredText に加えて、Sphinx Markup Constructs があって独自の付加的なマークアップも使えるようだ。

最後に、Pygments は、Python だけでなく、ActionScript や Apacheconf から始まって、C や C++、Java、Ruby、Perl は当然のこと、Haskel や Lua などの言語やスタイルシートの類等、実に対応が広いシンタックスハイライトの生成をしてくれるようだ。

Python のコードであれば、次のような感じでハイライトしてくれる。

from pygments import highlight
from pygments.lexers import PythonLexer
from pygments.formatters import HtmlFormatter

code = 'print "Hello World"'
print highlight(code, PythonLexer(), HtmlFormatter())


コマンドラインから、

$ pygmentize test.py

みたいなこともいろいろできる(オプションを指定するとあれこれ)。pygmentize -f html -o test.html test.py みたいにすると、下のようなものが生成される。

pygment.PNG






最終更新日  2008年03月23日 15時37分53秒
コメント(0) | コメントを書く
[Python] カテゴリの最新記事

Copyright (c) 1997-2019 Rakuten, Inc. All Rights Reserved.