Sphinxを使ってみた
技術資料をテキストファイルに記述して、リポジトリにコミットするとjenkinsでPDFとEPUBを生成してダウンロードできるような環境を作りたいと思い、ドキュメント生成用のツールとしてSphinxを試しに使ってみることにした。
作業環境はUbuntu12.04(VAIO type P, 2MB)
texliveインストール
作業環境にインストール済みだったので、Sphinx実行してみたところplatex -kanji=utf8が使用できなかったので、対応策を調べてみた。
Linux/Ubuntu - TeX Wiki
- Ubuntu 12.10 (Quantal Quetzal) には TeX Live 2012 が収録されています。
- UTF-8 に対応した pLaTeX が使用可能になっています。
- Ubuntu 12.10 の TeX Live 2012 が Ubuntu 12.04 にバックポートされています。
作業環境のtexliveを調べてみたらバージョンは不明だが2009年ものなのでかなり古い。
Ubuntu 12.04にバックポートされたTex Live 2012をインストールすることにした。
パッケージソースを追加してアップデートした。
$ sudo add-apt-repository ppa:texlive-backports/ppa $ sudo aptitude update
パッケージがバージョンアップされなかったようなので、インストール済みのtexliveパッケージを削除し、インストールし直した。
$ sudo aptitude remove '~ntexlive' $ aptitude search texlive | grep -e '^i'
$ sudo aptitude install texlive texlive-doc-ja texlive-lang-cjk texlive-latex-extra $ aptitude search texlive | grep -e '^i'
$ sudo aptitude install xdvik-ja dvipsk-ja ptex-bin
Sphinxドキュメントのひな形を作成
独学Linux : ゼロからはじめるSphinx《入門編》
以下のコマンドを実行し、ドキュメントのひな形を作成した。
$ mkdir testSphinx $ cd testSphinx $ 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 [.]: docs 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]: y 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: テスト文書 > Author name(s): 高松誠 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: 1.0 > Project release [1.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]: Sphinx can also add configuration for epub output: > Do you want to use the epub builder (y/N) [n]: y 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]: > intersphinx: link between Sphinx documentation of different projects (y/N) [n]: > todo: write "todo" entries that can be shown or hidden on build (y/N) [n]: > coverage: checks for documentation coverage (y/N) [n]: > pngmath: include math, rendered as PNG images (y/N) [n]: y > mathjax: include math, rendered in the browser by MathJax (y/N) [n]: > 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]: 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]: n Creating file docs/source/conf.py. Creating file docs/source/index.rst. Creating file docs/Makefile. Finished: An initial directory structure has been created. You should now populate your master file docs/source/index.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.
日本語用の設定
$ cd docs $ vi source/conf.py
以下の設定を追加
language = 'ja' latex_docclass = {'howto':'jsarticle','manual':'jsbook'}
htmlファイル生成
- コマンド実行
$ cd docs
$ make html
- 実行結果
sphinx-build -b html -d build/doctrees source build/html Making output directory... Running Sphinx v1.1.3 loading pickled environment... not yet created building [html]: targets for 1 source files that are out of date updating environment: 1 added, 0 changed, 0 removed reading sources... [100%] index /home/takamatu/Dropbox/work/testSphinx/docs/source/index.rst:7: WARNING: Title underline too short. Welcome to テスト文書's documentation! ================================= looking for now-outdated files... none found pickling environment... done checking consistency... done preparing documents... done writing output... [100%] index writing additional files... genindex search copying static files... done dumping search index... done dumping object inventory... done build succeeded, 1 warning. Build finished. The HTML pages are in build/html. $ ll build/html 合計 40 drwxrwxr-x 4 takamatu takamatu 4096 1月 7 13:58 ./ drwxrwxr-x 6 takamatu takamatu 4096 1月 7 13:58 ../ -rw-rw-r-- 1 takamatu takamatu 230 1月 7 13:58 .buildinfo drwxrwxr-x 2 takamatu takamatu 4096 1月 7 13:58 _sources/ drwxrwxr-x 2 takamatu takamatu 4096 1月 7 13:58 _static/ -rw-rw-r-- 1 takamatu takamatu 2756 1月 7 13:58 genindex.html -rw-rw-r-- 1 takamatu takamatu 3878 1月 7 13:58 index.html -rw-rw-r-- 1 takamatu takamatu 211 1月 7 13:58 objects.inv -rw-rw-r-- 1 takamatu takamatu 3126 1月 7 13:58 search.html -rw-rw-r-- 1 takamatu takamatu 269 1月 7 13:58 searchindex.js
epubファイル生成
- コマンド実行
$ make epub
- 実行結果
sphinx-build -b epub -d build/doctrees source build/epub Making output directory... Running Sphinx v1.1.3 loading pickled environment... done building [epub]: targets for 1 source files that are out of date updating environment: 0 added, 0 changed, 0 removed looking for now-outdated files... none found preparing documents... done writing output... [100%] index writing additional files... genindex search copying static files... done writing mimetype file... writing META-INF/container.xml file... writing content.opf file... WARNING: unknown mimetype for _static/jquery.js, ignoring WARNING: unknown mimetype for _static/doctools.js, ignoring WARNING: unknown mimetype for _static/searchtools.js, ignoring WARNING: unknown mimetype for _static/websupport.js, ignoring WARNING: unknown mimetype for _static/underscore.js, ignoring writing toc.ncx file... writing .epub file... build succeeded, 5 warnings. Build finished. The epub file is in build/epub. $ ll build/epub 合計 68 drwxrwxr-x 4 takamatu takamatu 4096 1月 7 13:58 ./ drwxrwxr-x 6 takamatu takamatu 4096 1月 7 13:58 ../ -rw-rw-r-- 1 takamatu takamatu 230 1月 7 13:58 .buildinfo -rw-rw-r-- 1 takamatu takamatu 23974 1月 7 13:58 .epub drwxrwxr-x 2 takamatu takamatu 4096 1月 7 13:58 META-INF/ drwxrwxr-x 2 takamatu takamatu 4096 1月 7 13:58 _static/ -rw-rw-r-- 1 takamatu takamatu 2630 1月 7 13:58 content.opf -rw-rw-r-- 1 takamatu takamatu 1186 1月 7 13:58 genindex.html -rw-rw-r-- 1 takamatu takamatu 1728 1月 7 13:58 index.html -rw-rw-r-- 1 takamatu takamatu 20 1月 7 13:58 mimetype -rw-rw-r-- 1 takamatu takamatu 2005 1月 7 13:58 search.html -rw-rw-r-- 1 takamatu takamatu 583 1月 7 13:58 toc.ncx
生成されたファイルが「.epub」なのは、文書タイトルが日本語のせいか？
PDFファイル生成
- コマンド実行
$ make latex
- 実行結果
sphinx-build -b latex -d build/doctrees source build/latex Making output directory... Running Sphinx v1.1.3 loading pickled environment... done building [latex]: all documents updating environment: 0 added, 0 changed, 0 removed looking for now-outdated files... none found processing .tex... index resolving references... writing... done copying TeX support files... done build succeeded. Build finished; the LaTeX files are in build/latex. Run `make' in that directory to run these through (pdf)latex (use `make latexpdf' here to do that automatically). $ ll build/latex 合計 88 drwxrwxr-x 2 takamatu takamatu 4096 1月 7 14:17 ./ drwxrwxr-x 6 takamatu takamatu 4096 1月 7 13:58 ../ -rw-rw-r-- 1 takamatu takamatu 1957 11月 1 2011 Makefile -rw-rw-r-- 1 takamatu takamatu 18775 10月 10 2011 fncychap.sty -rw-rw-r-- 1 takamatu takamatu 220 10月 10 2011 python.ist -rw-rw-r-- 1 takamatu takamatu 14711 1月 29 2012 sphinx.sty -rw-rw-r-- 1 takamatu takamatu 2417 1月 29 2012 sphinxhowto.cls -rw-rw-r-- 1 takamatu takamatu 3752 1月 29 2012 sphinxmanual.cls -rw-rw-r-- 1 takamatu takamatu 13836 10月 10 2011 tabulary.sty -rw-rw-r-- 1 takamatu takamatu 678 1月 7 14:16 texput.log -rw-rw-r-- 1 takamatu takamatu 6181 1月 7 13:58 .tex
生成されたファイルがEPUBと同じく「.tex」で名無し状態。
- コマンド実行
$ cd build/latex
$ make all-pdf-ja
- 実行結果
for f in *.pdf *.png *.gif *.jpg *.jpeg; do ebb $f; done ** WARNING ** Can't find file (*.pdf)...skipping ** WARNING ** Can't find file (*.png)...skipping ** WARNING ** Can't find file (*.gif)...skipping ** WARNING ** Can't find file (*.jpg)...skipping ** WARNING ** Can't find file (*.jpeg)...skipping for f in *.tex; do platex -kanji=utf8 $f; done This is e-pTeX, Version 3.1415926-p3.3-110825-2.4 (utf8.euc) (TeX Live 2012/Debian) restricted \write18 enabled. entering extended mode (./^83^^86^82鴻^^83^^88^96^^87^9bｸ.tex pLaTeX2e <2006/11/10> (based on LaTeX2e <2011/06/27> patch level 0) Babel <v3.8m> and hyphenation patterns for english, dumylang, nohyphenation, pi nyin, loaded. (./sphinxmanual.cls Document Class: sphinxmanual 2009/06/02 Document class (Sphinx manual) (/usr/share/texlive/texmf-dist/tex/latex/base/report.cls Document Class: sphinxmanual 2009/06/02 Document class (Sphinx manual) (/usr/share/texlive/texmf-dist/tex/latex/base/report.cls Document Class: report 2007/10/19 v1.4h Standard LaTeX document class (/usr/share/texlive/texmf-dist/tex/latex/base/size10.clo))) (/usr/share/texlive/texmf-dist/tex/latex/base/inputenc.sty (/usr/share/texlive/texmf-dist/tex/latex/base/utf8.def (/usr/share/texlive/texmf-dist/tex/latex/base/t1enc.dfu) (/usr/share/texlive/texmf-dist/tex/latex/base/ot1enc.dfu) (/usr/share/texlive/texmf-dist/tex/latex/base/omsenc.dfu))) (/usr/share/texlive/texmf-dist/tex/latex/base/fontenc.sty (/usr/share/texlive/texmf-dist/tex/latex/base/t1enc.def)) (/var/lib/texmf/tex/generic/babel/babel.sty (/usr/share/texlive/texmf-dist/tex/generic/babel/english.ldf (/usr/share/texlive/texmf-dist/tex/generic/babel/babel.def))) (/usr/share/texlive/texmf-dist/tex/latex/psnfss/times.sty) (./fncychap.sty) (/usr/share/texlive/texmf-dist/tex/latex/tools/longtable.sty) (./sphinx.sty (/usr/share/texlive/texmf-dist/tex/latex/base/textcomp.sty (/usr/share/texlive/texmf-dist/tex/latex/base/ts1enc.def (/usr/share/texlive/texmf-dist/tex/latex/base/ts1enc.dfu))) (/usr/share/texlive/texmf-dist/tex/latex/fancyhdr/fancyhdr.sty) (/usr/share/texlive/texmf-dist/tex/latex/fancybox/fancybox.sty Style option: `fancybox' v1.4 <2010/05/15> (tvz) ) (/usr/share/texlive/texmf-dist/tex/latex/titlesec/titlesec.sty) (./tabulary.sty (/usr/share/texlive/texmf-dist/tex/latex/tools/array.sty)) (/usr/share/texlive/texmf-dist/tex/latex/amsmath/amsmath.sty For additional information on amsmath, use the `?' option. (/usr/share/texlive/texmf-dist/tex/latex/amsmath/amstext.sty (/usr/share/texlive/texmf-dist/tex/latex/amsmath/amsgen.sty)) (/usr/share/texlive/texmf-dist/tex/latex/amsmath/amsbsy.sty) (/usr/share/texlive/texmf-dist/tex/latex/amsmath/amsopn.sty)) (/usr/share/texlive/texmf-dist/tex/latex/base/makeidx.sty) (/usr/share/texlive/texmf-dist/tex/latex/framed/framed.sty) (/usr/share/texlive/texmf-dist/tex/latex/base/ifthen.sty) (/usr/share/texlive/texmf-dist/tex/latex/graphics/color.sty (/usr/share/texlive/texmf-dist/tex/latex/latexconfig/color.cfg) (/usr/share/texlive/texmf-dist/tex/latex/graphics/dvips.def) (/usr/share/texlive/texmf-dist/tex/latex/graphics/dvipsnam.def)) (/usr/share/texlive/texmf-dist/tex/latex/fancyvrb/fancyvrb.sty Style option: `fancyvrb' v2.7a, with DG/SPQR fixes, and firstline=lastline fix <2008/02/07> (tvz) (/usr/share/texlive/texmf-dist/tex/latex/graphics/keyval.sty )) (/usr/share/texlive/texmf-dist/tex/latex/threeparttable/threeparttable.sty) (/usr/share/texlive/texmf-dist/tex/latex/mdwtools/footnote.sty) (/usr/share/texlive/texmf-dist/tex/latex/wrapfig/wrapfig.sty) (/usr/share/texlive/texmf-dist/tex/latex/parskip/parskip.sty) (/usr/share/texlive/texmf-dist/tex/latex/graphics/graphicx.sty (/usr/share/texlive/texmf-dist/tex/latex/graphics/graphics.sty (/usr/share/texlive/texmf-dist/tex/latex/graphics/trig.sty) (/usr/share/texlive/texmf-dist/tex/latex/latexconfig/graphics.cfg))) ! Undefined control sequence. l.186 ...n}{0.5em}{\py@TitleColor}{\py@NormalColor } ? ! Undefined control sequence. l.188 ...n}{0.5em}{\py@TitleColor}{\py@NormalColor } ? ! Undefined control sequence. l.190 ...n}{0.5em}{\py@TitleColor}{\py@NormalColor } ? ! Undefined control sequence. l.192 ...lor}{0em}{\py@TitleColor}{\py@NormalColor } ? (/usr/share/texlive/texmf-dist/tex/latex/hyperref/hyperref.sty (/usr/share/texlive/texmf-dist/tex/generic/oberdiek/hobsub-hyperref.sty (/usr/share/texlive/texmf-dist/tex/generic/oberdiek/hobsub-generic.sty)) (/usr/share/texlive/texmf-dist/tex/generic/ifxetex/ifxetex.sty) (/usr/share/texlive/texmf-dist/tex/latex/oberdiek/kvoptions.sty) (/usr/share/texlive/texmf-dist/tex/latex/hyperref/pd1enc.def) (/usr/share/texlive/texmf-dist/tex/latex/latexconfig/hyperref.cfg) (/usr/share/texlive/texmf-dist/tex/latex/url/url.sty)) Package hyperref Message: Driver (default): hdvips. (/usr/share/texlive/texmf-dist/tex/latex/hyperref/hdvips.def (/usr/share/texlive/texmf-dist/tex/latex/hyperref/pdfmark.def Package hyperref Warning: You have enabled option `breaklinks'. (hyperref) But driver `hdvips.def' does not suppport this. (hyperref) Expect trouble with the link areas of broken links. (/usr/share/texlive/texmf-dist/tex/latex/oberdiek/rerunfilecheck.sty))) (/usr/share/texlive/texmf-dist/tex/latex/oberdiek/hypcap.sty)) (/usr/share/texlive/texmf-dist/tex/latex/multirow/multirow.sty) Writing index file ^83^^86^82鴻^^83^^88^96^^87^9bｸ.idx No file ^83^^86^82鴻^^83^^88^96^^87^9bｸ.aux. (/usr/share/texlive/texmf-dist/tex/latex/base/ts1cmr.fd) (I search kanjifont definition file: . . ) (I search font definition file: . . . . . . . ) (/usr/share/texlive/texmf-dist/tex/latex/psnfss/t1ptm.fd) (/usr/share/texlive/texmf-dist/tex/latex/hyperref/nameref.sty (/usr/share/texlive/texmf-dist/tex/generic/oberdiek/gettitlestring.sty)) Package hyperref Warning: Rerun to get /PageLabels entry. (I search kanjifont definition file: . . ) (I search font definition file: . . . . . . . ) (/usr/share/texlive/texmf-dist/tex/latex/psnfss/t1phv.fd) LaTeX Font Warning: Font shape `JT1/gt/m/it' undefined (Font) using `JT1/gt/m/n' instead on input line 113. LaTeX Font Warning: Font shape `JY1/gt/m/it' undefined (Font) using `JY1/gt/m/n' instead on input line 113. LaTeX Font Warning: Font shape `JT1/gt/bx/it' undefined (Font) using `JT1/gt/bx/n' instead on input line 113. LaTeX Font Warning: Font shape `JY1/gt/bx/it' undefined (Font) using `JY1/gt/bx/n' instead on input line 113. [1] [2] Adding blank page after the table of contents. [1] [2] [1] [2] Chapter 1. (/usr/share/texlive/texmf-dist/tex/latex/psnfss/ts1ptm.fd) No file ^83^^86^82鴻^^83^^88^96^^87^9bｸ.ind. [3] (./^83^^86^82鴻^^83^^88^96^^87^9bｸ.aux) LaTeX Font Warning: Some font shapes were not available, defaults substituted. LaTeX Warning: Label(s) may have changed. Rerun to get cross-references right. ) Output written on ^83^^86^82鴻^^83^^88^96^^87^9bｸ.dvi (7 pages, 7184 by tes). Transcript written on ^83^^86^82鴻^^83^^88^96^^87^9bｸ.log. make: *** [all-pdf-ja] エラー 1 $ ll 合計 152 drwxrwxr-x 2 takamatu takamatu 4096 1月 7 14:27 ./ drwxrwxr-x 6 takamatu takamatu 4096 1月 7 13:58 ../ -rw-rw-r-- 1 takamatu takamatu 1957 11月 1 2011 Makefile -rw-rw-r-- 1 takamatu takamatu 18775 10月 10 2011 fncychap.sty -rw-rw-r-- 1 takamatu takamatu 220 10月 10 2011 python.ist -rw-rw-r-- 1 takamatu takamatu 14711 1月 29 2012 sphinx.sty -rw-rw-r-- 1 takamatu takamatu 2417 1月 29 2012 sphinxhowto.cls -rw-rw-r-- 1 takamatu takamatu 3752 1月 29 2012 sphinxmanual.cls -rw-rw-r-- 1 takamatu takamatu 13836 10月 10 2011 tabulary.sty -rw-rw-r-- 1 takamatu takamatu 678 1月 7 14:16 texput.log -rw-rw-r-- 1 takamatu takamatu 1187 1月 7 14:27 テスト文書.aux -rw-rw-r-- 1 takamatu takamatu 7184 1月 7 14:27 テスト文書.dvi -rw-rw-r-- 1 takamatu takamatu 0 1月 7 14:27 テスト文書.idx -rw-rw-r-- 1 takamatu takamatu 42139 1月 7 14:27 テスト文書.log -rw-rw-r-- 1 takamatu takamatu 53 1月 7 14:27 テスト文書.out -rw-rw-r-- 1 takamatu takamatu 6181 1月 7 13:58 テスト文書.tex -rw-rw-r-- 1 takamatu takamatu 100 1月 7 14:27 テスト文書.toc
