Sphinx - ドキュメンテーションビルダー

Sphinx

ディレクティブ

.. image::

画像を挿入します。

拡張機能

sphinx.ext.autodoc

Sphinxを使っているとreSTをPythonで生成して Sphinxに読み込ませたいと思うことがあります。 本来であれば拡張を作成するべきですがいろいろと面倒です。 なのでSphinx.ext.autodocを使って手っ取り早く実現します。 仕組みは簡単で、reSTを生成するスクリプトファイルを書き、 それのdocstringにreSTを入れてやるというものです。 Sphinxへの取り込みは automodule で取り込むだけです。

このサイトの 文字コード - 全文字制覇が私の夢です はそうやって作成しています。

取り込んでいるスクリプトは sys.path で届くところに配置しています。 コードはこの様になっています。

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
#-*- coding: utf-8 -*-
import reSTable
fields = ['char', 'binaries', 'octals', 'decimals', 'hexadecimals']
table = reSTable.GridTable(fields)
table._set_align('l') 

for ii in range(128):
    binary = '{0:08b}'.format(ii)
    octal = '{0:03o}'.format(ii)
    decimal = '{0:03d}'.format(ii)
    hexa = '{0:02x}'.format(ii)
    char = chr(ii)
    char = repr(char)
    if ii < 32:
        char = char.replace('\\', '\\\\')
    table.add_row([char, binary, octal, decimal, hexa])
__doc__ = str(table)

sphinx.ext.pngpmath

Extension error:
Could not import extension sphinx.ext.pngpmath (exception: No module named pngpmath)
Extension error:
jsmath_path config value must be set for the jsmath extension to work

sphinx.ext.oldmarkup

Extension error:
Could not import extension sphinx.ext.oldmarkup (exception: No module named oldmarkup)

sphinx.ext.todo - ToDoをドキュメント内に埋め込む

sphinx.ext.todo

Allow todos to be inserted into your documentation. Inclusion of todos can be switched of by a configuration variable. The todolist directive collects all todos of your project and lists them along with a backlink to the original location.

copyright:Copyright 2007-2013 by the Sphinx team, see AUTHORS.
license:BSD, see LICENSE for details.

ToDoをドキュメント内に書き込めるようになります。 使用するためには conf.pyextensionssphinx.ext.todo を追加します。

extensions.append('sphinx.ext.todo')
sphinx.ext.todo.todo_include_todos

ToDoを表示させるかどうかのスイッチです。 conf.py 内に記述します。 Trueであれば表示されます。Falseであれば表示されません。

.. todo::

1つToDoを表現します。

.. todolist::

定義されている todo ディレクティブの一覧に変換されます。

FAQ

make html 中に ERROR: Error in “py:module” directive: no content permitted.

モジュールの説明を書こうとして次のように記述しました。

reST:

.. py:module:: sphinx.ext.todo

   ToDoをドキュメント内に書き込めるようになります。
   使用するためには *conf.py* の *extensions* に *sphinx.ext.todo* を追加します。

するとmakeで次のようにエラーしました。

$ make html
sphinx.rst:11: ERROR: Error in "py:module" directive: no content permitted.

TIPS

改ページを設定する

page-break-after: alwaysスタイルの付いたタグを埋め込んでおくことで改ページさせられます。

.. raw:: html

   <p style="page-break-after: always" />

http://d.hatena.ne.jp/nishiohirokazu/20120102/1325503248

ソースコードファイルを読み込んでリテラルブロックとして表示

コードのブロックをページに載せるときコードのファイルからコピペするのは嫌ですよね。 コードのファイルが書き換わっても、ページは変わってくれません。

Sphinxではファイルから読み込んで リテラルブロックとして表示させるディレクティブ literalinclude が用意されています。

使い方は次のとおりです。

.. literalinclude:: _site-packages/reSTable.py
   :language: python
   :linenos:

この例では site-packages/reSTable.py というファイルを読み込んできて リテラルブロックとして表示します。 language はハイライトのための指定です。この例ではpythoのハイライトで表示されます。 linenos を指定した場合、行番号を表示します。

全てのドキュメントで使用できる置換を定義する

reSTの置換は |replace_string| と記述することで置換ができるようになっています。 そしてSphinxではデフォルトでいくつかのデフォルトの置換文字を定義しています。 置換に関しては 外部サイトの reStructuredText入門の置換インラインマークアップの置換 を確認してください。

複数のファイルで置換の定義を使う

置換定義の影響範囲はファイル内に閉じていて、他のファイルには影響しません。 しかし、複数のファイルにまたがって置換の定義を使用したい場合もあるでしょう。 そのような場面では include ディレクティブを使うと良いでしょう。

ファイルの先頭に次の記述を追加します。:

.. include:: definition.rst

こうすることでこれを記述したファイルには definition.rst内の置換定義が使えるようになります。

全てのファイルで置換の定義を使う

全てのファイルで置換の定義を使い回したい時もあります。 全てのファイに 複数のファイルで置換の定義を使う で説明した内容を 記述してもいいですが、ファイル数が多ければ結構面倒です。

その場合 conf.py に全てのファイルに 共通する内容を記述することができます。

conf.py (抜粋)

rst_prolog = u'''
.. include:: definition.rst_
'''

このように記述すると全てのrstファイルの先頭に rst_prolog の内容が記述されたのと同等なります。 つまり definition.rst_ に記述された定義が常に使えます。

ノート

ファイル名の最後にアンダースコアをつけています。 これは Sphinxdefinition.html というページを 作らせないための工夫です。 Sphinx は拡張子が .rst となっているファイルに対してページの生成を行います。 definition.rst_ に置換定義しか記述していないなら、 ページ作成の対象からはずしてしまったほうがいいからです。

全てのファイルで使用 ならば conf.py 内で定義する (ガセ)

警告

この方法は正しくありません。

この方法はたまにうまくいくとこともありますが、正しくありません。 使わないでください。 失敗例として、記事自体は残しておきます。 正しくは 全てのファイルで置換の定義を使う をご覧ください。

この置換の機能はデフォルトで一部の conf.py に記述された変数が利用可能です。 それは sphinx.environment.py に定義されている default_substitutions というset型の変数に使用可能な文字列が定義されているからです。

sphinx.environment.py (抜粋):

default_substitutions = set([
    'version',
    'release',
    'today',
])

この変数は conf.py 内で追加が可能です。 例えば conf.py には project という変数がありますが、 これをドキュメント全体で |project| として表現したい場合は conf.py 内に次を追加するだけで使用可能になります。

conf.py (抜粋):

import sphinx.environment
sphinx.environment.default_substitutions.add('project')

当然自分で定義したものも同様に使用できるようになります。

警告

この方法はsphinxのバージョンによってできなくなるようです。

ノート

前述した私の方法は裏技というか、反則というか。 とりあえず悪い見本として残しておきます。 ちゃんとドキュメント読んだり、ググったりしろってことですかね。 反省します。

特定のファイルは毎回ビルドする

例えば todolist などを貼り付けている場合、 他のファイルが変更になると内容が変わる可能性があります。 それらに対して普通にビルドすると todolist を記述したファイル自体は変わっていないためビルドされません。

それをビルドさせる方法の1つとしてタイムスタンプを変更する方法があります。

Windowsの場合、バッチファイルに記述

私の環境にはMinGWが入っているため touch が使えますが 中には使えない環境の方もいるでしょう。

そんなときの対策としてPythonワンライナーがあります。 Sphinxを使っている方でしたら必ずPythonが入っているはずです。 make.batの最初の方に記述しておけば毎回タイムスタンプを更新してくれます。

make.bat (抜粋):

python -c "import os; os.utime('todo.rst', None)"

勧めconf.py

このサイトの元になっているconf.pyを載せておきます。

# -*- coding: utf-8 -*-
#
# SXIMADA W3 documentation build configuration file, created by
# sphinx-quickstart on Sat Apr 13 05:55:31 2013.
#
# This file is execfile()d with the current directory set to its containing dir.
#
# Note that not all possible configuration values are present in this
# autogenerated file.
#
# All configuration values have a default; values that are commented out
# serve to show the default.

import sys, os

# If extensions (or modules to document with autodoc) are in another directory,
# add these directories to sys.path here. If the directory is relative to the
# documentation root, use os.path.abspath to make it absolute, like shown here.
sys.path.insert(0, os.path.abspath('_lib'))
sys.path.insert(0, os.path.abspath('_lib_'))



# -- General configuration -----------------------------------------------------

# If your documentation needs a minimal Sphinx version, state it here.
#needs_sphinx = '1.0'

# Add any Sphinx extension module names here, as strings. They can be extensions
# coming with Sphinx (named 'sphinx.ext.*') or your custom ones.
extensions = ['sphinx.ext.autodoc',
              'sphinx.ext.doctest',
              #'sphinx.ext.intersphinx',
              'sphinx.ext.todo',
              'sphinx.ext.coverage',
              'sphinx.ext.pngmath',
              #'sphinx.ext.mathjax',
              'sphinx.ext.ifconfig',
              'sphinx.ext.viewcode',
              'sphinxcontrib.autorun',
              'sphinxcontrib.plantuml',
              'sphinxcontrib.googleanalytics',
              'sphinxcontrib.blockdiag',
              #'sphinxcontrib.rubydomain',
              'blenderdomain',
              ]
todo_include_todos = False
plantuml = 'java -jar _lib_/plantuml.jar'
googleanalytics_id = 'UA-40118244-1'
googleanalytics_enabled = True

# Add any paths that contain templates here, relative to this directory.
templates_path = ['_templates']

# The suffix of source filenames.
source_suffix = '.rst'

# The encoding of source files.
#source_encoding = 'utf-8-sig'

# The master toctree document.
master_doc = 'index'

# General information about the project.
project = u'SXIMADA W3'
copyright = u'2013, sximada'

# The version info for the project you're documenting, acts as replacement for
# |version| and |release|, also used in various other places throughout the
# built documents.
#
# The short X.Y version.
version = '0.1'
# The full version, including alpha/beta/rc tags.
release = '0.1.0'

# The language for content autogenerated by Sphinx. Refer to documentation
# for a list of supported languages.
language = 'ja'

# There are two options for replacing |today|: either, you set today to some
# non-false value, then it is used:
#today = ''
# Else, today_fmt is used as the format for a strftime call.
#today_fmt = '%B %d, %Y'

# List of patterns, relative to source directory, that match files and
# directories to ignore when looking for source files.
exclude_patterns = []
import os, re
regx = re.compile('^_')
for root, dirs, files in os.walk(os.getcwd()):
    for name in filter(regx.search, dirs + files):
        path = os.path.relpath(os.path.join(root, name))
        exclude_patterns.append(path)


# The reST default role (used for this markup: `text`) to use for all documents.
#default_role = None

# If true, '()' will be appended to :func: etc. cross-reference text.
#add_function_parentheses = True

# If true, the current module name will be prepended to all description
# unit titles (such as .. function::).
#add_module_names = True

# If true, sectionauthor and moduleauthor directives will be shown in the
# output. They are ignored by default.
#show_authors = False

# The name of the Pygments (syntax highlighting) style to use.
pygments_style = 'sphinx'

# A list of ignored prefixes for module index sorting.
#modindex_common_prefix = []


# -- Options for HTML output ---------------------------------------------------

# The theme to use for HTML and HTML Help pages.  See the documentation for
# a list of builtin themes.
html_theme = 'oldschool'

# Theme options are theme-specific and customize the look and feel of a theme
# further.  For a list of options available for each theme, see the
# documentation.
#html_theme_options = {}

# Add any paths that contain custom themes here, relative to this directory.
html_theme_path = [os.path.abspath('_theme')]

# The name for this set of Sphinx documents.  If None, it defaults to
# "<project> v<release> documentation".
html_title = 'SXIMADA W3'

# A shorter title for the navigation bar.  Default is the same as html_title.
#html_short_title = None

# The name of an image file (relative to this directory) to place at the top
# of the sidebar.
html_logo = '_static/image.png'

# The name of an image file (within the static path) to use as favicon of the
# docs.  This file should be a Windows icon file (.ico) being 16x16 or 32x32
# pixels large.
#html_favicon = None

# Add any paths that contain custom static files (such as style sheets) here,
# relative to this directory. They are copied after the builtin static files,
# so a file named "default.css" will overwrite the builtin "default.css".
html_static_path = ['_static']

# If not '', a 'Last updated on:' timestamp is inserted at every page bottom,
# using the given strftime format.
html_last_updated_fmt = '%b %d, %Y'

# If true, SmartyPants will be used to convert quotes and dashes to
# typographically correct entities.
#html_use_smartypants = True

# Custom sidebar templates, maps document names to template names.
#html_sidebars = {}

# Additional templates that should be rendered to pages, maps page names to
# template names.
#html_additional_pages = {}

# If false, no module index is generated.
#html_domain_indices = True

# If false, no index is generated.
#html_use_index = True

# If true, the index is split into individual pages for each letter.
#html_split_index = False

# If true, links to the reST sources are added to the pages.
#html_show_sourcelink = True

# If true, "Created using Sphinx" is shown in the HTML footer. Default is True.
html_show_sphinx = True

# If true, "(C) Copyright ..." is shown in the HTML footer. Default is True.
#html_show_copyright = True

# If true, an OpenSearch description file will be output, and all pages will
# contain a <link> tag referring to it.  The value of this option must be the
# base URL from which the finished HTML is served.
#html_use_opensearch = ''

# This is the file name suffix for HTML files (e.g. ".xhtml").
#html_file_suffix = None

# Output file base name for HTML help builder.
htmlhelp_basename = 'SXIMADAW3doc'


# -- Options for LaTeX output --------------------------------------------------

latex_elements = {
# The paper size ('letterpaper' or 'a4paper').
#'papersize': 'letterpaper',

# The font size ('10pt', '11pt' or '12pt').
#'pointsize': '10pt',

# Additional stuff for the LaTeX preamble.
#'preamble': '',
}

# Grouping the document tree into LaTeX files. List of tuples
# (source start file, target name, title, author, documentclass [howto/manual]).
latex_documents = [
  ('index', 'SXIMADA W3.tex', u'SXIMADA W3 Documentation',
   u'takesxi sximada', 'manual'),
]

# The name of an image file (relative to this directory) to place at the top of
# the title page.
#latex_logo = None

# For "manual" documents, if this is true, then toplevel headings are parts,
# not chapters.
#latex_use_parts = False

# If true, show page references after internal links.
#latex_show_pagerefs = False

# If true, show URL addresses after external links.
#latex_show_urls = False

# Documents to append as an appendix to all manuals.
#latex_appendices = []

# If false, no module index is generated.
#latex_domain_indices = True


# -- Options for manual page output --------------------------------------------

# One entry per manual page. List of tuples
# (source start file, name, description, authors, manual section).
man_pages = [
    ('index', 'sximadaw3', u'SXIMADA W3',
     [u'Takesxi Sximada'], 1)
]

# If true, show URL addresses after external links.
#man_show_urls = False


# -- Options for Texinfo output ------------------------------------------------

# Grouping the document tree into Texinfo files. List of tuples
# (source start file, target name, title, author,
#  dir menu entry, description, category)
texinfo_documents = [
  ('index', 'SXIMADAW3', u'SXIMADA W3 Documentation',
   u'Takesxi Sximada', 'SXIMADAW3', 'One line description of project.',
   'Miscellaneous'),
]

# Documents to append as an appendix to all manuals.
#texinfo_appendices = []

# If false, no module index is generated.
#texinfo_domain_indices = True

# How to display URL addresses: 'footnote', 'no', or 'inline'.
#texinfo_show_urls = 'footnote'


# -- Options for Epub output ---------------------------------------------------

# Bibliographic Dublin Core info.
epub_title = u'SXIMADA W3'
epub_author = u'Takesxi Sximada'
epub_publisher = u'Takesxi Sximada'
epub_copyright = u'2013, Takesxi Sximada'

# The language of the text. It defaults to the language option
# or en if the language is not set.
#epub_language = ''

# The scheme of the identifier. Typical schemes are ISBN or URL.
#epub_scheme = ''

# The unique identifier of the text. This can be a ISBN number
# or the project homepage.
#epub_identifier = ''

# A unique identification for the text.
#epub_uid = ''

# A tuple containing the cover image and cover page html template filenames.
#epub_cover = ()

# HTML files that should be inserted before the pages created by sphinx.
# The format is a list of tuples containing the path and title.
#epub_pre_files = []

# HTML files shat should be inserted after the pages created by sphinx.
# The format is a list of tuples containing the path and title.
#epub_post_files = []

# A list of files that should not be packed into the epub file.
#epub_exclude_files = []

# The depth of the table of contents in toc.ncx.
#epub_tocdepth = 3

# Allow duplicate toc entries.
#epub_tocdup = True


# Example configuration for intersphinx: refer to the Python standard library.
intersphinx_mapping = {'http://docs.python.org/': None}

rst_prolog = u''
try:
    with open('_prolog.txt', 'rb') as ff:
        rst_prolog = ff.read().decode('utf8')
except IOError as err:
    print err

rst_epilog = u''
try:
    with open('_epilog.txt', 'rb') as ff:
        rst_epilog = ff.read().decode('utf8')
except IOError as err:
    print err


# sphinxcontrib_roles.py
extensions.append('sphinxcontrib_roles')
roles = {'strike': 'text-decoration: line-through;',
         'red': 'color: red;',
         }

#dqn
extensions.append('sphinxcontrib.dqndomain')

Sphinxcontrib

Sphinxにはたくさんの便利な拡張があります。 標準として入っていないので、別途インストールする必要があります。

どんなものがあるかは sphinx-contribのサイト に説明があります。

各パッケージはどれも同じリポジトリを使用していますが、 パッケージ毎にインストールスクリプトを持っていますので、1つずつ入れてください。 一気にやりたい人はスクリプトを書いてやる必要があります。

autorun

README.rst にあるサンプルコードを実行してみました。:

.. runblock:: pycon

    >>> for i in range(5):
    ...    print i

結果

>>> for i in range(5):
...    print i
... 
0
1
2
3
4

標準入出力を literalblock として表示させる機能のようです。 サンプルコードと実行結果を載せるときに、 いちいちコピペしなくてすみますね。

plantuml

インストールしたら早速付属のサンプルコードを実行してみます。:

.. uml::

   Alice -> Bob: Hi!
   Alice <- Bob: How are you?

実行結果。

Alice -> Bob: Hi!
Alice <- Bob: How are you?

上手くいきました。 どこかのサイトの説明にありましたが、確かにbuildの速度が落ちます(ソース紛失)。 UML ディレクティブのブロックはビルド時にどこかへキャッシュして 差分があった時だけ再生成するともっとよくなるかもしれません。

インストール時の注意

この拡張はインストール時に、上手くいきません。

$ python setup.py build
Traceback (most recent call last):
  File "setup.py", line 5, in <module>
    long_desc = open('README').read()
IOError: [Errno 2] No such file or directory: 'README'

これが発生するのは README というファイルがないからです。 同じ階層に README.rst というファイルがあります。 ファイル名が違っているのでダメです。 恐らく書き間違いでしょう。

setup.py の最初の方:

long_desc = open('README').read()

この箇所を:

long_desc = open('README.rst').read()

に変更すれば直ります。 こういう時って README.rst のファイルを修正するべきか、 setup.py の方のファイル名の指定を修正すべきか、 迷いますよね。(えっ!? どっちでもいいって!?)

残り

以下 https://bitbucket.org/birkenfeld/sphinx-contrib/ の引用です。 まだ試していませんが、試したら結果を記述していきます。:

aafig: render embeded ASCII art as nice images using aafigure.
actdiag: embed activity diagrams by using actdiag
adadomain: an extension for Ada support (Sphinx 1.0 needed)
ansi: parse ANSI color sequences inside documents
blockdiag: embed block diagrams by using blockdiag
cheeseshop: easily link to PyPI packages
clearquest: create tables from ClearQuest queries.
coffeedomain: a domain for (auto)documenting CoffeeScript source code.
context: a builder for ConTeXt.
doxylink: Link to external Doxygen-generated HTML documentation
email: obfuscate email addresses
erlangdomain: an extension for Erlang support (Sphinx 1.0 needed)
exceltable: embed Excel spreadsheets into documents using exceltable
feed: an extension for creating syndication feeds and time-based overviews from your site content
gnuplot: produces images using gnuplot language.
googleanalytics: track html visitors statistics
googlechart: embed charts by using Google Chart_
googlemaps: embed maps by using Google Maps_
httpdomain: a domain for documenting RESTful HTTP APIs.
hyphenator: client-side hyphenation of HTML using hyphenator
lilypond: an extension inserting music scripts from Lilypond in PNG format.
mockautodoc: mock imports.
mscgen: embed mscgen-formatted MSC (Message Sequence Chart)s.
nicoviceo: embed videos from nicovideo
nwdiag: embed network diagrams by using nwdiag
omegat: support tools to collaborate with OmegaT (Sphinx 1.1 needed)
osaka: convert standard Japanese doc to Osaka dialect (it is joke extension)
paverutils: an alternate integration of Sphinx with Paver.
phpdomain: an extension for PHP support
plantuml: embed UML diagram by using PlantUML
rawfiles: copy raw files, like a CNAME.
requirements: declare requirements wherever you need (e.g. in test docstrings), mark statuses and collect them in a single list
rubydomain: an extension for Ruby support (Sphinx 1.0 needed)
sadisplay: display SqlAlchemy model sadisplay
sdedit: an extension inserting sequence diagram by using Quick Sequence. Diagram Editor (sdedit)
seqdiag: embed sequence diagrams by using seqdiag
slide: embed presentation slides on slideshare and other sites.
swf: embed flash files
sword: an extension inserting Bible verses from Sword.
tikz: draw pictures with the TikZ/PGF LaTeX package.
traclinks: create TracLinks to a Trac instance from within Sphinx
whooshindex: whoosh indexer extension
youtube: embed videos from YouTube
zopeext: provide an autointerface directive for using Zope interfaces.
inserted by FC2 system