ドキュメント作成システム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”が「リリース」になったり，日付が「年月日」になったりする。この変更をはどこでしているのか？
• 行間の設定はどこでしているのか？

WWDC直前ですが，ドキュメント作成のお話を。

最近知ったのですが，1つのプレーンテキスト（reST）からPDF, html, ePub, Wordのドキュメントを生成するシステムSphinxが便利そうで，試行錯誤しています。

SphinxはPythonのドキュメント作成のための作られたシステムです。以下のリンクでSphinxのことがよく分かります。

Sphinxユーザー会

ドキュメントを作りたくなってしまう魔法のツールSphinx

Pythonのドキュメントを作れるシステムなので，

• コードハイライトがきれい。対応する言語も多い。
• 数式はTeXで処理するのできれい。
• プレーンテキストで書くので，Gitなどでバージョン管理可能。
• Python環境があれば，すぐにインストールできる。
• 関連するドキュメントが日本語化されている。

などいろいろいいところがあります。

reSTはreStructuredTextで，マークアップ言語の1種です。世間ではMarkdownのほうが知られていますが，似たような記法です。=, -, ^などで囲めばタイトルになり，+を頭につけるだけで箇条書きになるので，読みやすい文章がかけます。GithubやQiitaの原稿がMarkdownなので，Markdownを使うことが多いかと思います。その場合はPandocで変換できるので，reSTに変換することができるので，特に問題ないです。

htmlでざっくりかいて，確認して，完成版をPDFに変換するということができます。Wordで作文するのに飽きている人にはぜひおすすめします。