世界一短い、ドキュメント作成ツールSphinx入門

Sphinxとは?

ドキュメント作成ツールです。

Sphinx

エンジニアであれば、仕様書を作る際に役立ってくれるでしょう。

pdfやhtmlへの書き出しをサポートしているので、同じドキュメントを様々な閲覧形式にすることできます。

Sphinxには、sphinx-quickstartという簡易的にプロジェクトを作成できるコマンドが存在しますが、用意されるファイル群も多く、初心者には取っつきにくい印象です。

今回は手動で最大限にシンプルな構成のプロジェクトを作ってみます。

Linux・Macでの構築

インストール

pip install sphinx

ファイル・フォルダの作成

# touch index.rst
.. toctree::
   :caption: 概要
   :maxdepth: 2
   general/index
# touch conf.py
extensions = []
templates_path = ['_templates']
source_suffix = '.rst'
master_doc = 'index'
project = u'test'
copyright = u'2016, test'
author = u'test'
version = u'test'
release = u'test'
language = None
exclude_patterns = ['_build', 'Thumbs.db', '.DS_Store']
pygments_style = 'sphinx'
todo_include_todos = False
html_theme = 'alabaster'
html_static_path = ['_static']
htmlhelp_basename = 'testdoc'
latex_elements = {
}
latex_documents = [
    (master_doc, 'test.tex', u'test Documentation',
     u'test', 'manual'),
]
man_pages = [
    (master_doc, 'test', u'test Documentation',
     [author], 1)
]
texinfo_documents = [
    (master_doc, 'test', u'test Documentation',
     author, 'test', 'One line description of project.',
     'Miscellaneous'),
]
import sys, os
sys.path.insert(0, os.path.abspath('.'))
exclude_patterns = ['zzz']
numfig = True
extensions.append('sphinx.ext.todo')
extensions.append('sphinx.ext.autodoc')
extensions.append('sphinx.ext.intersphinx')
extensions.append('sphinx.ext.mathjax')
extensions.append('sphinx.ext.viewcode')
extensions.append('sphinx.ext.graphviz')
autosummary_generate = True
html_theme = 'default'

mkdir general

# touch general/index.rst

===========
hello world
===========

mkdir _static/

mkdir _build/

sphinx-build -E -b html ./ ./_build

_build以下にindex.htmlが作成されます。

以上、世界一短いSphinx入門でした。