3. LaTeX PDFのカスタマイズ

LaTeX PDFの出力に関する設定は、 conf.py への設定を基本とする。 より詳細な設定は 独自スタイルシートの適用 で説明する方法によってLaTeXコードを記載することによって行う。 本章の方針を 表 3.1 に示す。

表 3.1 本章のLaTeXカスタマイズの方針

設定場所

方針

設定言語
conf.py

  • latex_docclass

  • latex_docclass

ドキュメントクラスに関連する設定

Python
conf.py

  • latex_elements['preamble']

styファイルの読み込み

Python / LaTeX
conf.py

  • latex_elements['sphinxsetup']

Sphinxのstyファイルが提供するパラメータの設定

Python ([key=value,...])
conf.py

  • latex_elements[...]

その他のSphinxが用意している設定

Python

styファイル

LaTeXコードを記述する

LaTeX
参考サイト

ヒント

latex_elements['sphinxsetup'] はKeyの数が多くなると設定が長くなり、メンテナンス性が悪い。 以下のように、リストから展開するようにするとよい。

リスト 3.1 conf.pyの改善(sphinxsetup)
sphinxsetup = [
    "verbatimwithframe=false",          # コードブロックのボーダーを表示
    "VerbatimColor={rgb}{0.95,0.95,0.95}",      # コードブロックの背景色
    "InnerLinkColor={rgb}{0.2,0.2,0.2}",        # ドキュメント内のリンクの色
    "TableRowColorHeader={gray}{1.0}",          # 表のヘッダーの色(colorrows)
]
latex_elements['sphinxsetup'] = ",".join(sphinxsetup)

3.1. 独自スタイルシートの適用

conf.py の latex_elements['preamble'] は、restructuredTextから生成されるtexファイルの冒頭部分に挿入するLaTeXコードを定義する。 ここに直接LaTeXコードを記載してもよいが、メンテナンス性が下がる(コードハイライト、シンタックスチェックが利用できない、など)。 したがって、LaTeXコードはstyファイルに記述し、 latex_elements['preamble'] でそれを読み込むようにするとよい。

リスト 3.2 conf.py のstyファイル読み込み
latex_additional_files = ['mystyle.sty']  # mystyle.styを読み込み可能にする

latex_elements['preamble'] = r'\usepackage[]{mystyle}'

3.1.1. スタイルシートに引数を渡す

conf.py から独自定義したstyファイルに引数を与えたい場合、styファイルに以下のように記述する。 これは、タイトルページに独自の属性を追加したり、見た目の微調整をパラメータで行いたい場合などに有用である。

% ==================================
% パラメータの受け取り
% ==================================
\RequirePackage{kvoptions}

\SetupKeyvalOptions{
  family=myparam,
  prefix=myparam@
}

% \DeclareStringOption[default値]{オプション名}
\DeclareStringOption[hello]{testparam}      % パラメータtestparam:文字列型
\DeclareBoolOption[false]{testflag}         % パラメータtestflag:真偽値型

\ProcessKeyvalOptions*

渡された引数は、styファイル内で以下のように取得できる。 \typeout は、LaTeX PDFをコンパイルする際に標準出力にメッセージを表示するコマンドで例示している。

\typeout{testparam = \myparam@testparam}    % 文字列: プレフィックス@オプション名
\ifmyparam@testflag                         % 真偽値: \if...が宣言されるので条件分岐に使用
    \typeout{testflag = ON}
\fi

conf.py から独自定義したstyファイルに引数を与えたい場合、 \usepackage のオプション部分に引数を記述する。

latex_elements['preamble'] = r'\usepackage[testparam=ByeBye,testflag]{mystyle}'

ヒント

パラメータ数が多くなると、 \usepackage が長くなり、メンテナンス性が悪い。 以下のように、リストから展開するようにするとよい。

リスト 3.3 conf.pyの改善(preamble)
styleparams = [
    "testparam=ByeBye",
    "testflag",
]
latex_elements['preamble'] = rf'''
    \usepackage[{",".join(styleparams)}]{{mystyle}}
'''

3.2. 単位

Latexの長さの単位は以下の通り

表 3.2 長さの単位

pt

ポイント

in

インチ

mm

ミリメートル

cm

センチメートル

ex

欧文フォントの高さ

em

和文フォントの高さ

3.3. ドキュメントクラス

LaTeXでは、文書の基本的な性質を定義するためにtexファイルの冒頭で、 \documentclass を指定する。 基本書式は、以下の通りである。

\documentclass[<オプション>]{<クラス>}

Sphinxが生成するtexファイル \documentclass は、 conf.py の設定に基づいて生成される。 本節では、 conf.py の設定との対応関係を説明する。

3.3.1. クラス

conf.py の latex_documents に以下のようにタプルリストを設定することで指定できる。

latex_documents = [
    (<ルートドキュメント>, <texファイル名>, <タイトル>, <著者>, <Sphinxクラス>),
    ...
]

Sphinxには、独自のドキュメントクラスが定義されている。 このドキュメントクラスでは、既存のドキュメントクラスを使用してSphinx独自の設定が追加されたクラスである。 Sphinxクラスと設定内容の対応関係を 表 3.3 に示す。

表 3.3 Sphinxのドキュメントクラス

sphinxクラス

特徴

\documentclass で指定されるクラス

基本ドキュメントクラスのデフォルト

基本ドキュメントクラスのデフォルト(jp)

howto

タイトル～本文まで同じpagestyleが適用される。索引なし。

sphinxhowto

article

jreport

manual(デフォルト)

目次と本文で別のpagestyleが適用される。索引あり。

sphinxmanual

report

jsbook

ヒント

latex_documents に複数のタプルを設定することで、同時に複数のPDFファイルを作成できる。 ドキュメントルートの指定を細かく行うことで、セクションごとにPDFを出力するなどの応用ができる。 latex_documents を指定しない場合はデフォルトの設定(ドキュメントルートはindex、クラスはmanual、そのほかは project、 author をもとに設定。)が指定される。

基本ドキュメントクラスは、 conf.py の latex_docclass で上書きできる。指定例を以下に示す。

latex_docclass = {
    'howto': 'ltjsreport',
    'manual': 'ltjsarticle'
}

注釈

sphinx独自のドキュメントクラスは、 \chapter を使用するため、jsarticleクラスとは相性が悪い。

3.3.2. オプション

表 3.4 に \documentclass 影響する conf.py の設定を示す。

表 3.4 ドキュメントクラスのオプションに影響する変更

conf.py の設定値

説明

設定値の例

latex_elements ['pointsize']

本文のフォントサイズ

10pt 11pt 12pt

latex_elements ['papersize']

用紙サイズ

a4paper a5paper b4paper b5paper letterpaper jlreq

latex_elements ['extraclassoptions']

その他のオプション(片面/両面)

oneside twoside

その他のオプション(段組)

onecolumn twocolumn

その他のオプション(章おこし)

openany openright openleft

その他のオプション(ページの向き)

landscape

※その他のオプションは、すべてのドキュメントクラスで使用できるわけではない。a

3.4. 章タイトルのデザイン

titlesec パッケージを使用すると見出しの書式をカスタマイズできる。 カスタマイズは、 \part \chapter \section \subsection \subsubsection \paragraph \subparagraph の見た目を変更できる。

titleformatによる定義
1\titleformat{command}           % command=指定する命令
2    [shape]                     % hang,block,display,runin,leftmargin,rightmargin,drop,wrap,frame
3    {format}                    % 見出しの書式
4    {label-format}              % ラベル(1, 1.1など)の書式
5    {space-label-section}       % ラベルと見出しの間のスペース
6    {pre-section-code}          % 見出しの直前の内容
7    {post-section-code}         % 見出しの直後の内容
表 3.5 titleformatのshape

shape

挙動

hang

デフォルト。見出しが折り返すときは見出しの先頭位置に合わせる。

block

見出しは、ラベルも含めた全体で折り返す。

display

ラベルと見出しの間は改行する。

runin

本文は、見出しと同じ行から開始する。

drow/wrap

本文は、titlespacingより左及び右に割り込む。

frame

フレームで囲む
スペースの作成
1\hspace{width}      %横方向の空白を挿入
2\vspace{height}     %縦方向の空白を挿入
3
4\filright           % 右寄せ
5\filcenter          % 中央寄せ
6\filleft            % 左寄せ
7\fillast            % 最後の行は中央寄せ
装飾
1\titleline[align]{label}
2\titlerule                  % 線を引く
3\titlerule[width]           % 線を引く(太さ指定)
4\titlerule*[width]{text}    % 線を引く(特定の文字を埋める)
5
6\rule{width}{height}        % 黒い箱(width x height)を配置
7\rule[pos]{width}{height}   % 黒い箱(width x height)を高さ(pos)に配置
8
9\fbox{label}                % ラベルを文字で囲む

3.4.1. セクション開始時に改ページを挿入する

sectionbreakを再定義
\newcommand{\sectionbreak}{\clearpage}      % section開始直前に改ページする
\newcommand{\subsectionbreak}{\clearpage}   % subsection開始直前に改ページする

3.5. ヘッダ/フッタのカスタマイズ

Sphinxのヘッダ/フッタの定義は、 fancyhdr で定義されている。 fancyhdr は、 \fancypagestyle{} によってpagestyle毎にヘッダ/フッタの定義する。 sphinxでは、 sphinxlatexstylepage.sty にてその定義が行われている。

各ページで適用されるpagestyleを 表 3.6 に示す。 ただしこれは、Sphinxのpreambleやmaketitleなどでlatexコマンドを変更していない場合である。

表 3.6 Sphinxのページとpagestyle

適用ページ

pagestyle

タイトル

empty

目次

plain

目次(jsクラスの場合)

plainhead plainfoot

チャプターの先頭

plain

チャプターの先頭(jsクラスの場合)

plainhead plainfoot

空白ページ

empty

本文

normal
fancypagestyleによる定義
 1\fancypagestyle{<ページスタイル>}{
 2    \fancyhf{}  % 設定をリセット
 3    \fancyhead[L]{<ヘッダ左部の内容>}
 4    \fancyhead[R]{<ヘッダ右部の内容>}
 5    \fancyhead[C]{<ヘッダ中央部の内容>}
 6    \fancyhead[LO]{<奇数ページ:ヘッダ左部の内容>}
 7    \fancyhead[RO]{<奇数ページ:ヘッダ右部の内容>}
 8    \fancyhead[CO]{<奇数ページ:ヘッダ中央部の内容>}
 9    \fancyhead[LE]{<偶数ページ:ヘッダ左部の内容>}
10    \fancyhead[RE]{<偶数ページ:ヘッダ右部の内容>}
11    \fancyhead[CE]{<偶数ページ:ヘッダ中央部の内容>}
12
13    \fancyfoot[L]{<フッタ左部の内容>}
14    \fancyfoot[R]{<フッタ右部の内容>}
15    \fancyfoot[C]{<フッタ中央部の内容>}
16    \fancyfoot[LO]{<奇数ページ:フッタ左部の内容>}
17    \fancyfoot[RO]{<奇数ページ:フッタ右部の内容>}
18    \fancyfoot[CO]{<奇数ページ:フッタ中央部の内容>}
19    \fancyfoot[LE]{<偶数ページ:フッタ左部の内容>}
20    \fancyfoot[RE]{<偶数ページ:フッタ右部の内容>}
21    \fancyfoot[CE]{<偶数ページ:フッタ中央部の内容>}
22
23    \renewcommand{\headrulewidth}{0.4pt}    % ヘッダの境界の線の太さを変える
24    \renewcommand{\footrulewidth}{0.4pt}    % フッタの境界の線の太さを変える
25}
内容
 1\thepage        % 現在のページ数
 2
 3\RequirePackage{lastpage}
 4\pageref{LastPage}  % 最後のページ番号
 5
 6\leftmark       % チャプター情報
 7\rightmark      % セクション情報
 8
 9\today          % 日付
10
11\includegraphics[height=10pt]{logo.png} % 画像

3.6. 余白

geometryによる定義
1\RequirePackage{geometry}
2\geometry{
3    top=20mm,           %ページ上部
4    bottom=20mm,        %ページ下部
5    left=20mm,          %ページ左部
6    right=20mm          %ページ右部
7}

ヒント

twoside が設定されたドキュメントクラスを使用している場合、 左右の余白は偶奇ページで交互に入れ替わる。

3.7. 行間

再定義
\renewcommand{\baselinestretch}{0.75}

3.8. 定義リストのレイアウト崩れの修正

enumitemの設定変更
\usepackage{enumitem}
\setlist[description]{style=nextline}

3.9. コードブロックのデザイン

latex_elements['sphinxsetup'] による設定
sphinxsetup = [
    "verbatimhintsturnover=false",      # コードブロックがページをまたぐ場合のヒントを非表示
    "verbatimwithframe=false",          # コードブロックのボーダーを表示
    "verbatimborder=0.75pt",            # コードブロックのボーダーの幅
    "verbatimsep=0.2em",                  # コードブロックの余白
    "VerbatimColor={rgb}{0.95,0.95,0.95}",      # コードブロックの背景色
    "VerbatimBorderColor={rgb}{1.0,1.0,1.0}",   # コードブロックのボーダーの色
    "VerbatimHighlightColor={rgb}{1,1,1}",      # コードブロックのハイライト部分の色
]
latex_elements['sphinxsetup'] = ",".join(sphinxsetup)

3.10. インラインリテラルの見た目をHTML版に合わせる

Sphinx標準LaTeX PDFのデザインにおいて、 インラインリテラル のデザインは、単にフォントの変更と太字化のみの変更であり、HTML版の見た目と乖離がある。 HTML版と同様の見た目に変える場合、以下のようにstyファイルに定義する。

sphinxupquoteの上書き
\usepackage{tcolorbox}
\makeatletter

% 元の定義を退避
\let\orig@sphinxupquote\sphinxupquote

% 元の定義を上書き
\renewcommand{\sphinxupquote}[1]{
    \if\relax\detokenize{#1}\relax
        % 内容が空文字である場合、ボックスは使用しない
        \orig@sphinxupquote{#1}
    \else
        \tcbox[                 %tcboxで旧定義のsphinxupquoteを囲む
            on line,
            colframe=gray,      %見た目の調整
            colback=white,
            size=fbox,
            top=0pt,
            bottom=0pt,
            boxsep=1.2pt
        ]{%
            \orig@sphinxupquote{#1}
        }%
    \fi
}
\makeatother

3.11. 表のデザイン

latex_elements['sphinxsetup'] による設定
sphinxsetup = [
    "TableRowColorHeader={gray}{1.0}",          # 表のヘッダーの色(colorrows)
    "TableRowColorOdd={gray}{1.0}",             # 表の奇数列の色(colorrows)
    "TableRowColorEven={gray}{1.0}",            # 表の偶数列の色(colorrows)
]
latex_elements['sphinxsetup'] = ",".join(sphinxsetup)
styファイルによる微調整
\usepackage{longtable}              % ページを超えたテーブルを正しく描画する。
\setlength{\arrayrulewidth}{1.3pt}  % 罫線の太さ
\renewcommand{\arraystretch}{1}     % セルの行間
\setlength{\tabcolsep}{6pt}         % セルの横の余白

3.12. ハイパーリンク/内部参照の色の変更

latex_elements['sphinxsetup'] による設定
sphinxsetup = [
    "InnerLinkColor={rgb}{0.2,0.2,0.2}",        # ドキュメント内のリンクの色
    "OuterLinkColor={rgb}{0,0.1,0.5}",          # 外部リンクの色
]
latex_elements['sphinxsetup'] = ",".join(sphinxsetup)

3.13. タイトルページのデザイン

sphinxmaketitleの上書き
\renewcommand{\sphinxmaketitle}{
    \newgeometry{top=100mm}     % タイトルページ用余白
    \thispagestyle{title}       % タイトルページ用のヘッダ/フッタを設定

    \makeatletter       % twocolumnの場合は状態を保存してonecolumnに変更
    \newif\ifwas@twocolumn
        \if@twocolumn
        \was@twocolumntrue
        \onecolumn
    \else
        \was@twocolumnfalse
    \fi
    \makeatother

    % タイトル本文を記述する
    % @title = タイトル
    % @author = 著者
    % @date = 日付

    \makeatletter       % twocolumn設定だったらもとに戻す
    \ifwas@twocolumn
        \twocolumn
    \fi
    \makeatletter

    \restoregeometry % タイトルページ用余白をもとに戻す
    \clearpage
}