読者です 読者をやめる 読者になる 読者になる

ねこ元帥の中の人@リウマチ

日々の覚書など。ブログ名はオンラインゲームのアカウント名をいつも「ねこ元帥」にしているから。そして、2013年11月リウマチと診断されたとです。(2012年11月から時々手足に原因不明の痛みが発生、2013年9月以降は足の痛みが常態化、2013年12月30日からMTX服用開始、4月過ぎるころにはわずかの痛みが残る程度まで回復して現在に至る。)

Sphinxを使ってみた

linux tex sphinx

技術資料をテキストファイルに記述して、リポジトリにコミットするとjenkinsでPDFとEPUBを生成してダウンロードできるような環境を作りたいと思い、ドキュメント生成用のツールとしてSphinxを試しに使ってみることにした。

作業環境はUbuntu12.04(VAIO type P, 2MB)

Sphinxインストール

以下のコマンドでSphinxパッケージをインストールした。

$ sudo aptitude install python-sphinx

texliveインストール

作業環境にインストール済みだったので、Sphinx実行してみたところplatex -kanji=utf8が使用できなかったので、対応策を調べてみた。

  • Ubuntu 12.10 (Quantal Quetzal) には TeX Live 2012 が収録されています。
  • UTF-8 に対応した pLaTeX が使用可能になっています。
  • Ubuntu 12.10 の TeX Live 2012 が Ubuntu 12.04 にバックポートされています。
Linux/Ubuntu - TeX Wiki

作業環境の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  17 13:58 ./
drwxrwxr-x 6 takamatu takamatu  4096  17 13:58 ../
-rw-rw-r-- 1 takamatu takamatu   230  17 13:58 .buildinfo
-rw-rw-r-- 1 takamatu takamatu 23974  17 13:58 .epub
drwxrwxr-x 2 takamatu takamatu  4096  17 13:58 META-INF/
drwxrwxr-x 2 takamatu takamatu  4096  17 13:58 _static/
-rw-rw-r-- 1 takamatu takamatu  2630  17 13:58 content.opf
-rw-rw-r-- 1 takamatu takamatu  1186  17 13:58 genindex.html
-rw-rw-r-- 1 takamatu takamatu  1728  17 13:58 index.html
-rw-rw-r-- 1 takamatu takamatu    20  17 13:58 mimetype
-rw-rw-r-- 1 takamatu takamatu  2005  17 13:58 search.html
-rw-rw-r-- 1 takamatu takamatu   583  17 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  17 14:17 ./
drwxrwxr-x 6 takamatu takamatu  4096  17 13:58 ../
-rw-rw-r-- 1 takamatu takamatu  1957 111  2011 Makefile
-rw-rw-r-- 1 takamatu takamatu 18775 1010  2011 fncychap.sty
-rw-rw-r-- 1 takamatu takamatu   220 1010  2011 python.ist
-rw-rw-r-- 1 takamatu takamatu 14711  129  2012 sphinx.sty
-rw-rw-r-- 1 takamatu takamatu  2417  129  2012 sphinxhowto.cls
-rw-rw-r-- 1 takamatu takamatu  3752  129  2012 sphinxmanual.cls
-rw-rw-r-- 1 takamatu takamatu 13836 1010  2011 tabulary.sty
-rw-rw-r-- 1 takamatu takamatu   678  17 14:16 texput.log
-rw-rw-r-- 1 takamatu takamatu  6181  17 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  17 14:27 ./
drwxrwxr-x 6 takamatu takamatu  4096  17 13:58 ../
-rw-rw-r-- 1 takamatu takamatu  1957 111  2011 Makefile
-rw-rw-r-- 1 takamatu takamatu 18775 1010  2011 fncychap.sty
-rw-rw-r-- 1 takamatu takamatu   220 1010  2011 python.ist
-rw-rw-r-- 1 takamatu takamatu 14711  129  2012 sphinx.sty
-rw-rw-r-- 1 takamatu takamatu  2417  129  2012 sphinxhowto.cls
-rw-rw-r-- 1 takamatu takamatu  3752  129  2012 sphinxmanual.cls
-rw-rw-r-- 1 takamatu takamatu 13836 1010  2011 tabulary.sty
-rw-rw-r-- 1 takamatu takamatu   678  17 14:16 texput.log
-rw-rw-r-- 1 takamatu takamatu  1187  17 14:27 テスト文書.aux
-rw-rw-r-- 1 takamatu takamatu  7184  17 14:27 テスト文書.dvi
-rw-rw-r-- 1 takamatu takamatu     0  17 14:27 テスト文書.idx
-rw-rw-r-- 1 takamatu takamatu 42139  17 14:27 テスト文書.log
-rw-rw-r-- 1 takamatu takamatu    53  17 14:27 テスト文書.out
-rw-rw-r-- 1 takamatu takamatu  6181  17 13:58 テスト文書.tex
-rw-rw-r-- 1 takamatu takamatu   100  17 14:27 テスト文書.toc