Help us understand the problem. What is going on with this article?

Sphinxでドキュメントをpdf形式で出力する方法

はじめに

Python製のドキュメント作成ツール「Sphinx」では、html以外にもpdf形式で出力することができます。
本エントリでは、pdf形式で出力するまでの手順を説明します。

本エントリで説明すること

  • macOS上でSphinxでドキュメントをpdf形式で出力する方法

本エントリで説明しないこと

  • Sphinxの導入方法 ※導入方法は過去のエントリで紹介していますので、こちらをご覧ください
  • macOS以外で出力する方法
  • Sphinxがpdf形式で出力するまでの内部機構

前提

  • python3系をインスールしていること
  • Sphinx1.5以上をインストールしていること
  • 最新のhomebrewをインストールしていること
  • Sphinxのsphinx-quickstart実行時に、「source」ディレクトリと「build」ディレクトリを分けていること
参考(sphinx-quickstart実行時に聞かれる質問に以下のように答えると、ディレクトリが分かれます。)
# 英語版
$ sphinx-quickstart
> Separate source and build directories (y/N) [n]:y

# 日本語版
$ sphinx-quickstart
> ソースディレクトリとビルドディレクトリを分ける(y / n) [n]:y

筆者の環境

  • macOS Catalina 10.15.3
  • Python 3.7.4
  • Sphinx 2.4.4
  • Homebrew 2.2.11

参考:Pythonのバージョン確認手順

$ python -V
Python 3.7.4

参考:Sphinxのバージョン確認手順

$ pip show sphinx
Name: Sphinx
Version: 2.4.4
(以降は略)

参考:Homebrewのバージョン確認手順

$ brew --version
Homebrew 2.2.11
(以降は略)

PDF形式で出力するまでの流れ

  1. macOSにTeX環境を構築する
  2. conf.pyを書き換え、日本語で出力できるようにする
  3. make latexpdfを実行する

macOSにTeX環境を構築する

Sphinxでは、TeX(正確にはLaTeX)という形式を経由してreStructuredTextをpdf形式で出力することができます。
※Texは「てふ」と発音します。
※本エントリではTeX及び詳細な変換機構については説明しません。

以下のコマンドを打ち、macOSにTeX環境を構築します。

「brew cask install mactex-no-gui」はかなり時間が掛かります。
ちなみに、私の環境では6時間ぐらい掛かりました。

$ brew cask install mactex-no-gui

次の「sudo tlmgr update --self --all」ですが、
環境によっては「sudo tlmgr command not found」とエラーが出るかもしれません。
そのときは一度、ターミナルを閉じて、再度開いてからコマンドを打ってみてください。

ちなみに、このコマンドも時間が掛かります。私の環境では2時間ぐらい掛かりました。

$ sudo tlmgr update --self --all

conf.pyを書き換え、日本語で出力できるようにする

「source」ディレクトリ配下にあるconf.pyを開き、以下のように変更・追記し、保存してください。

# languageの部分を'ja'に変更する
language = 'ja'

# ファイル末尾に以下の行を追記する
latex_docclass = {'manual': 'jsbook'}

※latex_docclassには他にも様々な指定があるようですが、現在調査中です。

make latexpdfを実行する

Makefileがあるディレクトリで以下のコマンドを実行すると、「build/latex」にpdfができています。

$ make latefpdf

参考文献

t-shmp
分かりやすい記事を心がけます
Why not register and get more from Qiita?
  1. We will deliver articles that match you
    By following users and tags, you can catch up information on technical fields that you are interested in as a whole
  2. you can read useful information later efficiently
    By "stocking" the articles you like, you can search right away
Comments
No comments
Sign up for free and join this conversation.
If you already have a Qiita account
Why do not you register as a user and use Qiita more conveniently?
You need to log in to use this function. Qiita can be used more conveniently after logging in.
You seem to be reading articles frequently this month. Qiita can be used more conveniently after logging in.
  1. We will deliver articles that match you
    By following users and tags, you can catch up information on technical fields that you are interested in as a whole
  2. you can read useful information later efficiently
    By "stocking" the articles you like, you can search right away
ユーザーは見つかりませんでした