====== Sphinx ======

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

===== このページについて =====

インストール記録

  * OS:FreeBSD
  * Python：pyenv + pyenv-virtualenv


===== インストール =====

Python環境の構築は【[[development:language:python:pyenv|]]】を参照

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

# 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を使用する。インストールは[[serverapps:lighttpd|]]を参照。

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

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

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