Sphinxでドキュメント作成!! (自分用メモ 編集中)

インストール方法

$ pip3 install sphinx

# ブロックダイアグラム記述用
$ pip3 install blockdiag

conf.pyを編集します。

# blockdiagを追加する
extensions = ['sphinxcontrib.blockdiag']

# Fontpath for blockdiag (truetype font)
blockdiag_fontpath ='/Library/Fonts/Osaka.ttf'
blockdiag_antialias = True

プロジェクト作成方法

ドキュメントを作成するためのプロジェクト作成を行います。 sphinx-quickstartを実行して対話的に作成できるようですが、非対話で作成する方法を示します。

# sphinx-quickstart -q -p <project_name> -a <author> -v <project_version> <project_directory>

注意

index.rstにページを追加していくように使うみたいですが…

index.rstの :maxdepth: 2 の最初の:に追加するものを揃えないとエラーが発生するようです。

.. sampler documentation master file, created by
   sphinx-quickstart on Thu Oct  1 02:29:34 2015.
   You can adapt this file completely to your liking, but it should at least
   contain the root `toctree` directive.

 Welcome to sampler's documentation!
 ===================================

Contents:

.. toctree::
    :maxdepth: 2

    進捗1
    進捗2



Indices and tables
==================

* :ref:`genindex`
* :ref:`modindex`
* :ref:`search`

pdf出力するために

conf.pyに以下を追加

# 言語の設定
language = 'ja'

# LaTeX の docclass 設定
latex_docclass = {'manual': 'jsbook'}

LaTeXを使ってPDFを生成すると、紙とフォントサイズを変更しただけのconf.pyの設定内容だと、章の間に空ページが入ります。 本のために空白を入れているみたいなのでレポート形式に変更します。

latex_elements = {
...
'extraclassoptions': 'report',
...
}

以下を実行

$ make latex
$ make -C _build/latex all-pdf-ja