ドキュメント作成システムSphinxが便利という話を書きました。PDFを出力する方法は2つあって，rst2pdfという拡張を使う方法とLaTeXのファイルをつくってPDFに変換する方法です。ここでは自動で生成されるTeXのフォーマットを変更する方法について述べます。Sphinxは1.2.2を使ってます。
LaTeXでPDFを作るにはまずTeXを一式インストールしておく必要があります。これはユーザー会のサイトに詳しい説明があります。
SphinxとLaTeXの設定が終わったとして，いざ日本語のドキュメントを作ってみると，ドキュメントクラスにjsarticleを使っていてもかなり個性的なフォーマットになっています。気に入らないので，SphinxのTeXソース自動生成の設定を変更します。（ただし，まだ試行錯誤中なので，完全に自分の好みにするには至ってません）
まずSphinxのPythonのソースコードを見ます。MacPortsでMacにインストールした場合は/opt/local/Library/Frameworks/Python.framework/Versions/2.7/lib/python2.7/site-packages/sphinx/にSphinxのソースコードがあります。他の方法でインストールした場合は適宜探して下さい。
このディレクトリには多くのファイルがあります。 lsで見てみると，
__init__.py config.pyc locale/ setup_command.pyc __init__.pyc directives/ make_mode.py texinputs/ addnodes.py domains/ make_mode.pyc themes/ addnodes.pyc environment.py pycode/ theming.py apidoc.py environment.pyc pygments_styles.py theming.pyc apidoc.pyc errors.py pygments_styles.pyc transforms.py application.py errors.pyc quickstart.py transforms.pyc application.pyc ext/ quickstart.pyc util/ builders/ highlighting.py roles.py versioning.py cmdline.py highlighting.pyc roles.pyc versioning.pyc cmdline.pyc jinja2glue.py search/ websupport/ config.py jinja2glue.pyc setup_command.py writers/
がでます。今回変更するのはconfig.py, quickstart.py, writerのlatex.py, texinputsのsphinx.sty, sphinxhowto.cls, sphinxmanual.clsです。
まず，config.pyです。Sphinxではデフォルトの用紙サイズがletterpaperになっているので，a4paperに変更します。これはconfig.pyの中のlatex関係の設定のところにあります。
– latex_paper_size = (‘letter’, None),
+ latex_paper_size = (‘a4’, None),
latex_paper_sizeの設定を変更します。git diffの様子(-が修正前，+が修正後です。以下同様）
sphinxにはsphinx-quickstartという必要なファイルを一気に作ってくれるコマンドがあります。便利なのですが，LaTeXのreportクラスを使う”manual”がデフォルトになっています。LaTeXのarticle (jsarticle)クラスを使う”howto”をデフォルトにします。これはquickstart.pyにあります。quickstart.py内に自動生成するconf.pyの内容がそのまま書いてあるので，そこのLaTeX関連のところを変更します。
– u’%(author_texescaped_str)s’, ‘manual’),
+ u’%(author_texescaped_str)s’, ‘howto’),
上のように自動生成するタイプを変更します。
次にwriterディレクトリのlatex.pyを変更します。このファイルで，元のreSTファイルからTeXのソースファイルを生成するための設定を行っていると思われます。デフォルトの行間が広すぎ気がするので，行間を狭くするように設定しました。全体の行間指定をどこで行っているのかよくわからないので，とりあえず\baselinestretchのコマンドを挿入するようにしました。\baselinestrechを1以下にすると全体の行間が狭くなります。TeXソースの最初のほうに設定が入るように，BEGIN_DOCを以下のように設定しました。
BEGIN_DOC = r”’
\begin{document}
%(shorthandoff)s
\renewcommand{\baselinestretch}{0.8}
”’
途中にdefault_elementsという設定があるので，とりあえず余計な設定は消しました。ここでもpapersizeとpointsizeがありますが，ここだけ変更しても反映されません。config.pyの修正が必要になります。
default_elements = {
‘papersize’: ‘a4paper’,
‘pointsize’: ’10pt’,
‘classoptions’: ”,
‘extraclassoptions’: ”,
‘inputenc’: ‘\\usepackage[utf8]{inputenc}’,
‘utf8extra’: ‘\\DeclareUnicodeCharacter{00A0}{\\nobreakspace}’,
‘cmappkg’: ‘\\usepackage{cmap}’,
‘fontenc’: ‘\\usepackage[T1]{fontenc}’,
‘babel’: ‘\\usepackage{babel}’,
‘fontpkg’: ”,
‘fncychap’: ”,
‘longtable’: ‘\\usepackage{longtable}’,
‘preamble’: ”,
‘title’: ”,
‘date’: ”,
‘release’: ”,
‘author’: ”,
‘logo’: ”,
‘releasename’: ‘Release’,
‘makeindex’: ‘\\makeindex’,
‘shorthandoff’: ”,
‘maketitle’: ‘\\maketitle’,
‘tableofcontents’: ‘\\tableofcontents’,
‘footer’: ”,
‘printindex’: ‘\\printindex’,
‘transition’: ‘\n\n\\bigskip\\hrule{}\\bigskip\n\n’,
}
TeXのドキュメントクラスにjsarticle, jsbookを使いたいので，以下のようにしました。
if document.settings.docclass == ‘howto’:
docclass = builder.config.latex_docclass.get(‘howto’, ‘jsarticle’)
else:
docclass = builder.config.latex_docclass.get(‘manual’, ‘jsbook’)
Sphinxで自動生成されたLaTeXのソースファイルが参照している，sphinx.sty, sphinxhowto.cls, sphinxmanual.clsを変更します。ドキュメントをhowtoにすると，sphinxhowto.cls，manualにするとsphinxmanual.clsが使われます。とりあえずここではsphinxhowto.clsを使うとします。manualの場合は適宜読み替えて下さい。
ページ番号が表示されるようにpagestyleをplainにします。sphinx.styにあります。
\pagestyle{plain}
最初のページのページスタイルはsphinxhowto.clsで指定していますので，それを修正します。ページスタイルが全体で統一されるように81行目あたりの\thispagestyleをコメントアウト。
%\thispagestyle{empty}
デフォルトだと，howtoでsection, subsection, manualでchapter, sectionにしか番号がふられないので，番号がふられる階層を深くします。sphinxhowto.clsのsecnumdepthを変えます。
% Set some sane defaults for section numbering depth and TOC depth. You can
% reset these counters in your preamble.
%
-\setcounter{secnumdepth}{2}
+\setcounter{secnumdepth}{3}
タイトルと目次を変更します。sphinxhowto.clsを修正します。デフォルトの設定だとタイトル部分が広すぎるので，狭くなるように文字サイズを縮小して，リリース番号を消去しました。仕切りの横罫線も消すようにしました。
% Change the title page to look a bit better, and fit in with the fncychap
% “Bjarne” style a bit better.
%
\renewcommand{\maketitle}{
% \rule{\textwidth}{1pt}
\ifsphinxpdfoutput
\begingroup
% These \defs are required to deal with multi-line authors; it
% changes \\ to ‘, ‘ (comma-space), making it pass muster for
% generating document info in the PDF file.
\def\\{, }
\def\and{and }
\pdfinfo{
/Author (\@author)
/Title (\@title)
}
\endgroup
\fi
\begin{center}
\sphinxlogo%
{\Large \@title} \par
% {\em\large\py@HeaderFamily \py@release\releaseinfo} \par
% \vspace{20pt}
\end{center}
\begin{flushright}
\@date \hspace{3zw} \@author \par
% {\large
% \begin{tabular}[t]{c}
% \@author
% \end{tabular}} \par
%% \vspace{2pt}
\py@authoraddress \par
\end{flushright}
目次の横罫線を消去。
\let\py@OldTableofcontents=\tableofcontents
\renewcommand{\tableofcontents}{
\begingroup
\parskip = 0mm
\py@OldTableofcontents
\endgroup
% \rule{\textwidth}{1pt}
\vspace{12pt}
}
結局のところ，Sphinxが生成するLaTeXのフォーマットの変更はwriterのlatex.py, texinputsのsphinx.sty, sphinxhowto.cls, sphinxmanual.clsの修正で行えます。これらの修正はTeXの知識が必要になってきます。今回書いたことがSphinxユーザーの役に立てば幸いです。
疑問なこともまだあります。情報あれば教えて下さい。
- languageをjaにすると日本語設定になる。”release”が「リリース」になったり，日付が「年月日」になったりする。この変更をはどこでしているのか？
- 行間の設定はどこでしているのか？