目次

Sphinx

ドキュメント生成ツール。python製

このページについて

インストール記録

インストール

Python環境の構築は【pyenv + pyenv-virtualenv】を参照

依存パッケージをインストール

# pkg install gmake

今回、sphinxはpipで入れる

$ pip install sphinx

うまくインストールされていれば、以下のコマンドでバージョンとオプションが表示される

$ sphinx-build -h

pillow

依存パッケージをインストール

# pkg install tk86 webp openjpeg
$ pip install pillow

reportlab

$ pip install reportlab

blockdiag

$ pip install blockdiag
$ pip install sphinxcontrib-blockdiag
$ pip install sphinxcontrib-actdiag
$ pip install sphinxcontrib-nwdiag
$ pip install sphinxcontrib-seqdiag

フォントのインストール

# pkg install ja-font-genshingothic

設定

conf.py

extensions = [
  'sphinx.ext.todo', 
  'sphinx.ext.coverage',
  'sphinx.ext.imgmath',
  'sphinxcontrib.seqdiag',
  'sphinxcontrib.blockdiag',
  'sphinxcontrib.actdiag',
  'sphinxcontrib.nwdiag',
  'sphinxcontrib.rackdiag'
]
# -- Font ----------------------------------------------------------------------
# Fontpath 
actdiag_fontpath   = '/usr/local/share/fonts/genshingothic/GenShinGothic-Monospace-Medium.ttf'
blockdiag_fontpath = '/usr/local/share/fonts/genshingothic/GenShinGothic-Monospace-Medium.ttf'
seqdiag_fontpath   = '/usr/local/share/fonts/genshingothic/GenShinGothic-Monospace-Medium.ttf'

図に日本語を利用する場合は、必ず blockdiag_fontpath が必要

ビルド

Makefileのある場所で

$ gmake html
または
$ sphinx-build -b html sourcedir builddir

httpサーバで表示

今回は、lighttpdを使用する。インストールはlighttpdを参照。

# vi /usr/local/etc/lighttpd/lighttpd.conf 
server.document-root = server_root + "/sphinx/build/html"

いろいろな形式に変換する

対象 利用するもの メモ
pdf rst2pdf 過去の遺物
blockdiag等の外部拡張が反映されない
LaTeX経由 設定が面倒
blockdiag等の外部拡張が反映される