この記事は
PDFなどのドキュメント生成ツールであるSphinxの利用入門です。
テキストファイルからドキュメント生成するにはpandocなどもありますが、ある程度大規模なドキュメント生成するにはpandocでは辛く、Sphinxが今の所お手軽さと自由度（できること）の幅がちょうど良いツールかなと思っています。
- macOSを対象に書いています。
- ドキュメント記述ルールは順次追記していきます。
サンプル
以下に、実際にSphinxを利用してドキュメント記述し、
pdfとhtmlをビルドしてみたサンプルを置いています。
https://github.com/sakaeda11/sphinx-study
- 上のリポジトリの内容のビルド結果（github page）
- pdf: sphinx-study.pdf
- html: index.html
github actionでsphinxのインストール、ビルド、github pageへのデプロイを行っています。
基本手順
1.インストール
1.1.sphinxのインストール
お手元のmacにbrewがインストールされていれば以下のコマンドで。
$brew install sphinx-doc
※インストール方法は他にもありますがここでは割愛
1.2.mactex(mactex-no-gui)のインストール
Sphinxでpdfを出力するにはmactexが必要になるのでインストールします。
$brew install --cask mactex-no-gui
(環境にも寄ると思いますが10〜20分ぐらいかかります)
→ここで私の環境では
Error: Cask 'mactex-no-gui' conflicts with 'basictex'.
と表示されインストール失敗。。
macでtex環境を削除を参考にbasictexを削除してから再度mactex-no-guiのインストール実行しました。
mactexのインストール後、最新状態にアップデートします。
$sudo tlmgr update --self --all
※tlmgrはTeXのパッケージ管理ツール
こちらの処理も30分〜1時間ぐらいかかりました。
2.初期設定
以下のコマンドで初期セットアップを行います。
これを利用しない手順もあるにはあるのですが、面倒になるだけなので極力利用しましょう。
$sphinx-quickstart
対話式で「パス、ディレクトリ設定、プロジェクト名、著者名、言語」などのが聞かれるので入力すると各種ファイルが作成されます。
ここで「ソースディレクトリとビルドディレクトリを分ける(y/n)」という選択肢が出てきますが、この記事ではyを選択した前提で話を進めます。
設定すると以下のようなファイルとディレクトリが作成されます。
- build/ : ビルド結果が置かれるディレクトリ
-
source/
- _static/ : 画像などのリソースを置くディレクトリ
- _templates/ :
- conf.py : 設定ファイル
- index.rst : ルートドキュメントファイル
- make.bat : makeビルド用ファイル（Windows用）
- Makefile : makeビルド用ファイル
3.ドキュメント記述
rstファイルを記述していきます。
この詳細は多岐に渡るので一旦デフォルトで生成されるindex.rstだけで次のビルドに進んでみましょう。
（ドキュメント記述の仕方は本ページの下の方に記載します。）
4.ビルド
※sphinx-buildコマンドでビルドする方法と、sphinx-quickstartで生成されたMakefileを元にmakeコマンドでビルドする方法の2通りがありますが、基本はmakeを利用します。
$make [ビルダー]
ビルダーには色々ありますが、pdfを作成する場合はlatexpdfを指定します
$make latexpdf
するとbuild/latex/のディレクトリにプロジェクト名（sphinx-quickstartで指定したもの）のpdfファイルが生成されています。
その他
設定ファイル（conf.py）
- sphinx-quickstartによって
source/conf.pyに作成される設定ファイル - プロジェクト名や、著者名、各種拡張設定などが記述される
- python構文で記述されている
- 詳細はConfigurationを参照のこと
Autodoc
- Sphinxではpythonのドキュメントを生成する機能も充実している
- pythonソースコード上の
docstringsというコメントを読み取ってドキュメント化してくれます。 - 利用する場合はconf.pyに
extensions = ['sphinx.ext.autodoc']と記述してこの機能を有効化する - Intersphinxという機能を利用すると、オンライン上のpythonドキュメントへのリンクを自動生成してくれる機能ももある
- pythonソースコード上の
- 詳細はAutodocを参照のこと
テーマ
- htmlを生成した際のデザインをテーマという形で設定できます
- pdf生成時のデザイン変更はこの機能ではできません。LaTeX customization
やOptions for LaTeX output
を参照して設定して下さい。
- pdf生成時のデザイン変更はこの機能ではできません。LaTeX customization
- conf.pyの
html_themeというパラメータにテーマを指定します- テーマには様々なものがあり、自身で作成することができます。
- 詳細はHTML Themingを参照のこと
ドキュメント記述について(rstファイルの書き方)：reStructuredText
Sphinxでは基本的にreStructuredTextというファイル（拡張子rst）という書式でドキュメントを記述します。
このreStructuredTextはDocutilsによって提供されたものですが、これ元にSphinxでは独自の機能も追加して利用しています。
基本構文
→githubとgithub page上に随時書き足して行ってますのでそちらを参照して下さい。
github:sphinx-study
PDF Sample
HTML Sample
Directive（ディレクティブ）
ディレクティブはreStructuredTextを拡張するための機構
Directiveのフォーマット
.. {ディレクティブタイプ}:: {パラメータ(オプション)}
{パラメータ(オプション)}
:
<空白行>
{コンテンツ}
- ".. "とピリオド２つと半角スペースで始まる
- ディレクティブタイプは様々な物がある
- 大文字小文字に区別はない
- 1単語（スペースを含めない文字列）
- ディレクティブの後には":: "とコロン２つと半角スペースが続く
- ディレクティブマーカーという
- ディレクティブマーカーの後や、次の行からはディレクティブタイプ次第
- ディレクティブマーカーのパラメータやコンテンツになる
- 次の行から記述されるパラメータはインデントで始まる
- インデントの方式にはっきりした決まりは無いが、半角スペース3つで表現することが多い
- コンテンツは、一行空白行を開けてから始まる
主なディレクティブ
toctree
tocはTOC、Table of contentの略
rstファイルを分割して扱う場合に利用する
-
相対パスでも絶対パスでも指定できる
- 相対パスは、そのファイルからの相対パス
- 絶対パスはsourceディレクトリからのパスを示す
-
入れ子にできる
- toctreeで埋め込まれたファイルの中で更にtoctreeを記述できる
-
出力フォーマットによって、リンクになるか、埋め込みになるかは異なる
- HTMLなど複数ファイル形式の場合はリンク
- PDFなどは埋め込み
math
数式を記述するためのディレクティブ
.. math::
(a + b)^2 &= (a + b)(a + b) \\
&= a^2 + 2ab + b^2
csv-table
テーブルの記述方法はいくつかありますが、ディレクティブを使った書き方は書きやすいです。
.. csv-table::
a,b,c
1,2,3
todo & todolist
個人的に重宝しているのがこのディレクティブ
利用する際は先に以下のようにconf.pyに設定追記する必要があります。
extensions = [
+ 'sphinx.ext.todo',
]
+todo_include_todos = True
- estensionの追加
- todo_include_todosの有効化
その上で、rst上に
.. todo:: TODOの内容
と記述することで、TODOの枠が表示されます。
また、
.. todolist::
というディレクティブを記述すると、ドキュメント全体からtodoを探し出してリストアップしてくれます。
翻訳（i17n）
参考：Sphinxで作る貢献しやすいドキュメント翻訳の仕組み
ドキュメントの翻訳版を用意したい場合は以下の流れで行います。
0.事前準備
sphinx-intlのインストールと、locale_dirsの指定
pip install sphinx-intl
language = 'ja'
+locale_dirs = ['locale']
1.ドキュメントからpot（Potable Object Template）ファイルを生成します。
make gettext
→build/gettext 以下にpotファイルが生成されます。
2.potファイルからlocaleディレクトリ以下に対象言語コードとしてのpoファイルを生成します
sphinx-intl update -p build/gettext -l ja
→{locale_dirs}/ja以下にpoファイルが生成されます。
3.poファイルの対象のmsgidに対するmsgstrに翻訳ワードを記述します。
#: ../../src/chapter-1/chapter-1-1/2.基本的なドローンの構成.rst:73
#: ../../src/chapter-1/chapter-1-1/2.基本的なドローンの構成.rst:82
#: ../../src/chapter-1/chapter-1-1/2.基本的なドローンの構成.rst:84
msgid "課題"
msgstr ""
↓
#: ../../src/chapter-1/chapter-1-1/2.基本的なドローンの構成.rst:73
#: ../../src/chapter-1/chapter-1-1/2.基本的なドローンの構成.rst:82
#: ../../src/chapter-1/chapter-1-1/2.基本的なドローンの構成.rst:84
msgid "課題"
msgstr "TODO"
4.pdfやhtmlをビルドします。
make latexpdf
5.本文に更に変更があり、追加で翻訳していく場合は
1 のmake gettextから繰り返します。
その他の設定
PDFで空白ページを生成させない
Sphinxで生成されるPDFはデフォルトでは書籍をターゲットにしていて、適切に空白ページを入れ込みます。
便利な機能ですが、単にPDFとして生成したいときはこの空白ページは邪魔になります。
これを止めたい場合はconf.pyに以下のように記述します。
latex_elements = {
'extraclassoptions': 'openany'
}
以下の参考サイトでは openanyだけではなくopenany,onesideと書いてあったりしますが、onesideと書くことによる違いは今の所よく分かってません💦
参考1:Sphinx docs: Remove blank pages from generated PDFs?
参考2:Sphinx(latex→PDF)で余計な空白ページを消す方法