Symfony2のドキュメントをbuildする
先日Symfony2本家サイトが落ちてましたが、ドキュメントを参照できなくなるのはかなり辛いです。逆にPHPはマニュアルがあちこちのサイトに乗っかってて、なかなか本家に辿りつけないわけですが:-(
で、ドキュメントをダウンロードしておこうと思ったらPDF形式なんですよね。。。さすがに使いづらい。
んじゃあ、githubからダウンロードしてくるかと思い、GitHub - symfony/symfony-docs: The Symfony documentationに行ってみると拡張子が"rst"のファイルがゾロゾロ。。。どうもbuildする必要がありそうな気配。
ということで、やってみました。
今回の環境
- CentOS5.4
- Python2.4.3(rpm版)
事前準備
Symfony2のドキュメントはSphinxというPython製ドキュメンテーションビルダーを使っているようで、まずはSphinxをインストールする必要があります。
python-setuptoolsをインストール後、easy_installコマンドでインストールします。
$ sudo yum install -y python-setuptools $ sudo easy_install -U Sphinx
build手順
基本的な手順はOne developer's blog: How to generate symfony 2 documentationにありますが、微妙に異なってました。
1. ソースの取得
ここは特に問題無いと思います。
$ mkdir work $ cd work/ $ git clone https://github.com/symfony/symfony-docs.git $ git clone https://github.com/fabpot/sphinx-php.git
2. build設定
sphinx-quickstartコマンドを実行し、対話形式で出力先などの設定を決定していきます。ちと長いですが、以下の様な感じ。
$ cd symfony-docs/ $ sphinx-quickstart Welcome to the Sphinx 1.1.3 quickstart utility. Please enter values for the following settings (just press Enter to accept a default value, if one is given in brackets). Enter the root path for documentation. > Root path for the documentation [.]: You have two options for placing the build directory for Sphinx output. Either, you use a directory "_build" within the root path, or you separate "source" and "build" directories within the root path. > Separate source and build directories (y/N) [n]: Inside the root directory, two more directories will be created; "_templates" for custom HTML templates and "_static" for custom stylesheets and other static files. You can enter another prefix (such as ".") to replace the underscore. > Name prefix for templates and static dir [_]: The project name will occur in several places in the built documentation. > Project name: Symfony2 > Author name(s): foo@example.com Sphinx has the notion of a "version" and a "release" for the software. Each version can have multiple releases. For example, for Python the version is something like 2.5 or 3.0, while the release is something like 2.5.1 or 3.0a1. If you don't need this dual structure, just set both to the same value. > Project version: 2.0 > Project release [2.0]: The file name suffix for source files. Commonly, this is either ".txt" or ".rst". Only files with this suffix are considered documents. > Source file suffix [.rst]: One document is special in that it is considered the top node of the "contents tree", that is, it is the root of the hierarchical structure of the documents. Normally, this is "index", but if your "index" document is a custom template, you can also set this to another filename. > Name of your master document (without suffix) [index]: Error: the master file index.rst has already been found in the selected root path. sphinx-quickstart will not overwrite the existing file. > Please enter a new file name, or rename the existing file and press Enter [index]: home Sphinx can also add configuration for epub output: > Do you want to use the epub builder (y/N) [n]: Please indicate if you want to use one of the following Sphinx extensions: > autodoc: automatically insert docstrings from modules (y/N) [n]: y > doctest: automatically test code snippets in doctest blocks (y/N) [n]: y > intersphinx: link between Sphinx documentation of different projects (y/N) [n]: y > todo: write "todo" entries that can be shown or hidden on build (y/N) [n]: y > coverage: checks for documentation coverage (y/N) [n]: y > pngmath: include math, rendered as PNG images (y/N) [n]: y > mathjax: include math, rendered in the browser by MathJax (y/N) [n]: y Note: pngmath and mathjax cannot be enabled at the same time. pngmath has been deselected. > ifconfig: conditional inclusion of content based on config values (y/N) [n]: > viewcode: include links to the source code of documented Python objects (y/N) [n]: y A Makefile and a Windows command file can be generated for you so that you only have to run e.g. `make html' instead of invoking sphinx-build directly. > Create Makefile? (Y/n) [y]: > Create Windows command file? (Y/n) [y]: Creating file ./conf.py. Creating file ./home.rst. Creating file ./Makefile. Creating file ./make.bat. Finished: An initial directory structure has been created. You should now populate your master file ./home.rst and create other documentation source files. Use the Makefile to build the docs, like so: make builder where "builder" is one of the supported builders, e.g. html, latex or linkcheck.
One developer's blog: How to generate symfony 2 documentationには「index.rstをコピーしてsphinx-quickstartコマンド実行後に書き戻せ」とありますが、
> Name of your master document (without suffix) [index]:
のところで"index"を指定できないようなのでindex.rstのコピーは行なっていません。
3. conf.pyの編集
続いて、カレントディレクトリに作成されたconf.pyを編集します。One developer's blog: How to generate symfony 2 documentationとの違いは以下のとおり。
$ cp -p conf.py conf.py.org $ vi conf.py $ diff conf.py.org conf.py 14a15 > sys.path.append(os.path.abspath('../sphinx-php/sensio/sphinx')) 28c29 < extensions = ['sphinx.ext.autodoc', 'sphinx.ext.doctest', 'sphinx.ext.intersphinx', 'sphinx.ext.todo', 'sphinx.ext.coverage', 'sphinx.ext.pngmath', 'sphinx.ext.mathjax', 'sphinx.ext.viewcode'] --- > extensions = ['sphinx.ext.autodoc', 'sphinx.ext.doctest', 'sphinx.ext.intersphinx', 'sphinx.ext.todo', 'sphinx.ext.coverage', 'sphinx.ext.pngmath', 'sphinx.ext.mathjax', 'sphinx.ext.viewcode'<strong>, 'configurationblock'</strong>] $
4. build実行
ここまで来ればめでたくbuild実行できるハズなんですが、例外が発生し強制終了されました。。。orz
$ make html sphinx-build -b html -d _build/doctrees . _build/html Making output directory... Running Sphinx v1.1.3 Exception occurred: File "/usr/lib/python2.4/copy_reg.py", line 92, in __newobj__ return cls.__new__(cls, *args) TypeError: function() takes at least 2 arguments (0 given) The full traceback has been saved in /tmp/sphinx-err-TelODf.log, if you want to report the issue to the developers. Please also report this if it was a user error, so that a better error message can be provided next time. Either send bugs to the mailing list at <http://groups.google.com/group/sphinx-dev/>, or report them in the tracker at <http://bitbucket.org/birkenfeld/sphinx/issues/>. Thanks! make: *** [html] エラー 1 $
で、ググってみたところ、ピンポイントで情報を見つけました。
どうやら、Sphinxが依存している(?)PygmentsというライブラリがPython 2.4をサポートしていないことに起因しているようで、1つ前のバージョンをインストールするとうまくいったという報告がありました。
ということで、Pygmentsを入れなおします。
$ sudo easy_install -m Pygments Searching for Pygments Best match: Pygments 1.5 Processing Pygments-1.5-py2.4.egg Removing Pygments 1.5 from easy-install.pth file Installing pygmentize script to /usr/bin Using /usr/lib/python2.4/site-packages/Pygments-1.5-py2.4.egg Because this distribution was installed --multi-version, before you can import modules from this package in an application, you will need to 'import pkg_resources' and then use a 'require()' call similar to one of these examples, in order to select the desired version: pkg_resources.require("Pygments") # latest installed version pkg_resources.require("Pygments==1.5") # this exact version pkg_resources.require("Pygments>=1.5") # this version or higher Processing dependencies for Pygments $ $ sudo easy_install http://pypi.python.org/packages/2.4/P/Pygments/Pygments-1.4-py2.4.egg#md5=619325b28c60a1ac96ba1c9b301149c6 $ $ sudo easy_install -m Pygments Searching for Pygments Best match: Pygments 1.5 Processing Pygments-1.5-py2.4.egg Removing Pygments 1.4 from easy-install.pth file Installing pygmentize script to /usr/bin Using /usr/lib/python2.4/site-packages/Pygments-1.5-py2.4.egg Because this distribution was installed --multi-version, before you can import modules from this package in an application, you will need to 'import pkg_resources' and then use a 'require()' call similar to one of these examples, in order to select the desired version: pkg_resources.require("Pygments") # latest installed version pkg_resources.require("Pygments==1.5") # this exact version pkg_resources.require("Pygments>=1.5") # this version or higher Processing dependencies for Pygments $
で、再度build実行。
$ make html sphinx-build -b html -d _build/doctrees . _build/html Running Sphinx v1.1.3 ： copying static files... done dumping search index... done dumping object inventory... done build succeeded, 289 warnings. Build finished. The HTML pages are in _build/html. $
今度はうまくいきました:-)
