aptpod Tech Blog

株式会社アプトポッドのテクノロジーブログです

SphinxとLuaLaTeXで、日本語PDFマニュアルを作る

ドキュメンティング

f:id:aptpod_tech-writer:20200715105149j:plain

アプトポッドにて、テクニカルライターとして製品マニュアルの制作を担当している篠崎です。

現在弊社では、製品マニュアルの制作に、Sphinxを導入しようとしています。Sphinxは、1つの原稿ファイルからHTML、PDF等を出力できるドキュメントジェネレーターです。この記事では、SphinxにLuaLaTeXを組み合わせて日本語PDFを生成する方法を探ってみました。

背景

弊社では以前から、マニュアル制作にソフトウェア開発の手法を取り入れつつ、作業の効率化に取り組んできました。その様子については、以下のような記事でご紹介したことがあります。

いずれも大変効果的な手法だったのですが、最近、マニュアルの内容を継続的にアップデートしていく上で、いくつかの課題が生じており、他の方法の検討も進めています。

そんななか、候補としてSphinxを使ってみることにしました。Sphinxは、reStructuredText記法で書かれた原稿を、HTMLウェブページやPDF、ePubなどに変換してくれるドキュメント生成ツールです。最初からウェブページとPDFの両方に対応しているというのが大きな魅力です。（注：ウェブページを作成するための静的サイトジェネレーターは世の中にたくさんありますが、PDF出力には対応していない場合がほとんどです。好みの静的サイトジェネレーターに別のPDF作成ツールを組み合わせるのは魅力的な選択肢ですが、それはそれで大仕事になります。）

Sphinxでは、PDF出力はLaTeX経由で行われます。reStructuredText記法で原稿を書いてPDF作成コマンドを実行すると、Sphinxにより原稿がLaTeXファイルに変換され、その後、LaTeXエンジンによりPDFに変換されます。なお、LaTeXエンジンはSphinxには含まれませんので、別途インストールする必要があります。TeX Liveを使ってインストールするのが便利です。

f:id:aptpod_tech-writer:20200713200005p:plain
Sphinxを使って、reStructuredTextからPDFを作成する

Sphinxを試し始めたところ、弊社の製品マニュアル用としてはいくつかの課題が浮かび上がりました。そのうち1つがフォントです。弊社では、スマートで美しいAXISフォントをウェブアプリケーションや印刷物で使用しています。以前の記事のようにWordでマニュアルを作成する際も、AXISフォントを使用し、PDFに埋め込んでいました。Sphinxを使う場合も、ぜひこのフォントを使用したいと考えました。Sphinxの場合、PDF出力は前述のようにLaTeX経由で行われるため、LaTeXでこのフォントを使う必要があります。しかしLaTeXでのフォントの扱いは簡単ではありません。

調べてみたところ、LaTeXエンジンの1つであるLuaLaTeXを使うと、より簡単にフォントの変更ができることが分かりました。Sphinxでの日本語PDF出力には、デフォルトではpLaTeXが使われますが、設定によりLuaLaTeXに変更することができます。以下ではLuaLaTeXを使う場合の設定例を紹介します。

（Sphinxは、設定ファイルconf.pyによりさまざまな設定が可能です。また、それ以外にもカスタマイズのための入り口が多数用意されており、柔軟に変更できます。）

SphinxでLuaLaTeXを使う設定

新しくSphinxのドキュメントプロジェクトを作って、最小限の設定を行うところを解説します。

使用した環境は以下の通りです。

  • Windows 10
  • Sphinx v3.0.2（※ v3.1.0~を使用すると、以下に紹介する設定ではうまくいかないことが分かっています*1）
  • TeX Live 2020

まずは、sphinx-quickstartコマンドを使ってプロジェクトディレクトリを作成します。端末でsphinx-quickstartを実行すると通常は対話モードになり、プロジェクト名などを順々に入力しなければなりませんが、-qオプションを使うと、非対話モードで実行することができます。

sphinx-quickstart -q -p サンプルマニュアル -a 株式会社〇〇 -v 1.0 -l ja sample_manual

このコマンドにより、以下のようにプロジェクトディレクトリが作成されます。

  • プロジェクト名(-pオプション): サンプルマニュアル
  • 著者(-aオプション): 株式会社〇〇
  • プロジェクトバージョン(-vオプション): 1.0
  • 言語(-lオプション): 日本語（ja）
  • ディレクトリ名: sample_manual

プロジェクトディレクトリの中には、原稿ファイルindex.rst、設定ファイルconf.py、そのほか必要なサブディレクトリが作成されます。conf.pyには、プロジェクト名や著者の設定がすでに書き込まれています。以下のようになっているはずです。

（省略）

# -- Project information -----------------------------------------------------

project = 'サンプルマニュアル'
copyright = '2020, 株式会社〇〇'
author = '株式会社〇〇'

# The short X.Y version
version = '1.0'

# The full version, including alpha/beta/rc tags
release = '1.0'


# -- General configuration ---------------------------------------------------

（省略）

language = 'ja'

（省略）

ここで、sample_manualディレクトリに移動し、make latexpdfコマンドを実行すると、_buildディレクトリにPDFが出力されます。このPDFはデフォルトのpLaTeXにより出力されたものです。

LuaLaTeXを使用するためには、設定ファイルconf.pyにlatex_engine = 'lualatex'を追加します。しかしこれだけではエラーになってしまいます。日本語のプロジェクト（language = 'ja'）では、自動的に、LaTeXのjsbookドキュメントクラスが使用されるためです。jsbookはpLaTeXでの処理を必要とするので、これが読み込まれる段階でエラーになります。そこで、使用するドキュメントクラスを変更し、以下のように設定しました。これでコンパイルエラーなしでPDFが出力されるようになります。

併せて、当初の目標に沿って、AXISフォントを使用する設定を書き込みました（使用するフォントは、LuaLaTeXが認識する場所にインストールされている必要があります）。

# -- Options for LaTeX output -------------------------------------------------

# (A) LuaLaTeXを使用する
latex_engine = 'lualatex'

# (B) LaTeXドキュメントクラスとしてltjsbookを使用する
latex_docclass = {'manual': 'ltjsbook'}

latex_elements = {
    # (C) Polyglossiaパッケージを読み込まないようにする
    'polyglossia': '',

    # (D) サンセリフ系フォント、ゴシック系フォントを指定する（AXISフォントを使用するため）
    'fontpkg': r'''
\usepackage[no-math,scale=1.0]{luatexja-fontspec}
\setsansfont{AxisStd-Regular.otf}[
  BoldFont = AxisStd-Medium.otf
]

\setsansjfont{AxisStd-Regular.otf}[
  BoldFont = AxisStd-Medium.otf
]
''',

   # (E) デフォルトのフォントをサンセリフ系、ゴシック系に変更する（AXISフォントを使用するため）
   'preamble': r'''
\renewcommand\familydefault{\sfdefault}
\renewcommand\kanjifamilydefault{\gtdefault}
'''

}

ご覧のように、latex_elementsのfontpkgやpreambleに指定された文字列は、LaTeXのコマンドそのものです。これらは、SphinxによってLaTeXファイルに書き込まれます。

このように設定すると、LuaLaTeXにより以下のようなPDFが出力されました。

f:id:aptpod_tech-writer:20200713200137p:plain
LuaLaTeXにより生成されたPDF

ポイントは以下の通りです。記号(A)~(E)は上のコード内の記号に対応しています。

(A) LuaLaTeXを使用する

前述のとおり、LaTeXエンジンとしてLuaLaTeXを使用します。

(B) LaTeXドキュメントクラスとしてltjsbookを使用する

Sphinxで日本語PDFを出力するとき、標準ではjsbookドキュメントクラスが使用されますが、それに代えてltjsbookドキュメントクラスを使用します。ltjsbookは、jsbookをもとにしたLuaLaTeX対応のドキュメントクラスです。TeX Liveに含まれていますので、Tex Liveがインストールされていれば使用することができます。

(C) Polyglossiaパッケージを読み込まないようにする

SphinxでLuaLaTeXを使用すると、標準ではLaTeXのPolyglossiaパッケージが読み込まれます。Polyglossiaは、LaTeXでの多言語組版を可能にするパッケージですが、今回の例で使用すると、以下のようなフォントに関する警告が多数出力されます。

Package polyglossia Warning: Asking to add empty feature to latin font(Script="CJK" to scripttag "") on input line xx.

今回はPolyglossiaパッケージを使用する必要はないので、これをオフにしています。

(D) サンセリフ系フォント、ゴシック系フォントを指定する（AXISフォントを使用するため）

luatexja-fontspecパッケージを使って、フォントを指定します。

弊社の場合は、ここでAXISフォントを指定します。AXISフォントはゴシック系のフォントですので、また、和文だけでなく欧文（文中の英数字）にも使用したいので、setsansfontとsetsansjfontの両方を行います。基本書体としてAxisStd-Regular.otfを、ボールド書体としてAxisStd-Medium.otfをそれぞれ設定しました。

no-mathオプションは、数式部分のフォント設定を変更しないために指定しています。

scaleオプションは、欧文フォントに対する和文フォントのサイズの比率を設定するものです。和文と欧文に別々のフォントを使用する場合に、大きさのバランスを調整するのに使用します。今回は、和文と欧文ともに同じAXISフォントを使用するため、バランスを調整する必要はありませんが、指定をしないとltjsbookドキュメントクラスが持つ\Cjascaleの値（0.924715）が使用されるため、scale=1.0を指定しています。

(E) デフォルトのフォントをサンセリフ系、ゴシック系に変更する（AXISフォントを使用するため）

ltjsbookの本文のフォントは、欧文はセリフ系、和文は明朝になっています。これをサンセリフ系、ゴシック系に変更します。これにより、本文の欧文部分、和文部分ともに上記(D)で指定したAXISフォントが使用されます。

おわりに、今後に向けて

以上のように設定することで、AXISフォントを指定し、LuaLaTeXを使って日本語のPDFを出力できるようになりました。紹介した例は説明用の最小限のもので、マニュアル制作の実務では、ここからさまざまな設定や、スタイルの調整が必要になります。

また、実務でSphinxを活用するにあたっては、PDFの出力方法以外にも、ウェブページ出力のための設定、翻訳の方法など、検討しなければならないことはいくつもあります。

今回のPDF作成により、Sphinxは柔軟にカスタマイズが可能で、使いやすいツールであることが分かりました。これを効率的なマニュアル制作に活用できるよう、今後も知恵を絞りたいと思っています。

参考文献

*1:Sphinx v3.1.0~では、言語設定をjaにすると、pLaTeX専用のpxjahyperパッケージが読み込まれるためです。対処方法は別途検討したいと思います。