SphinxのLaTeXのフォーマットをいじる

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

こちらもどうぞ

SphinxのLaTeXのフォーマットをいじる」への2件のフィードバック

  1. > languageをjaにすると日本語設定になる。”release”が「リリース」になったり,日付が「年月日」になったりする。この変更をはどこでしているのか?

    rst -> transform(日本語への変換) -> builder(latexソースの作成) -> writer(latexコマンド実行)
    という順番で動作しています。

    > 行間の設定はどこでしているのか?

    特に記載はないのでデフォルトの値を使っているのではないでしょうか。
    なお、ご存知だとは思いますが、

    ¥renewcommand{¥baselinestretch}{2.0}

    などとpreambleに付け加えれば、行間を変えられます。

    • どうもアドバイスありがとうございます。日本語への変換の技術がどうなってるのか知らなかったので,参考になります。

      正解かはわかりませんが,locale/ja/LC_MESSAGES内のsphinx.poを編集して,msgfmtで処理したら,翻訳される部分の文言を変更できました。

      TeXのコマンドをconf.pyのプリアンブルに設定できたんですね。最近知りました。
      ブログの記事には行間と書きましたが,よく考えると自分がやりたかったのはパラグラフ間の間隔の調整でした。
      \parskip=0zw
      \parindent=1zw
      をプリアンブルで設定することで,割りと好みの感じになりました。ただし,英語のときはデフォルトのほうがいいかと思いますが。

コメントを残す

メールアドレスが公開されることはありません。