macでhomebrew・pyenv・pipを使ってsphinxの環境を構築する

ドキュメント生成ツールであるsphinxをmacのローカル環境にインストールし、動作するところまでまとめてみます。

sphinxとは

sphinx-users.jp
sphinxはPython製ドキュメンテーションビルダーで、markdownのようなフォーマットに従ってテキストを書いてビルドすると、htmlやwordやpdfやtex等が生成できます。詳細はsphinxのサイトをご覧下さい。

では早速環境構築をしてみましょう。

pyenv

OSのバージョンによって初期インストールされているpythonのバージョンが異なったりするので、OSに依存せず初期インストールとは別に別途pythonをインストールするため、pyenvを導入します。macの場合はhomebrewでインストールすると楽です。homebrewならアインインストールも簡単です。

インストール

tree-no-iMac:~ tree$ brew install pyenv
==> Downloading https://homebrew.bintray.com/bottles/pyenv-20150404.yosemite.bottle.tar.gz
######################################################################## 100.0%
==> Pouring pyenv-20150404.yosemite.bottle.tar.gz
==> Caveats
To enable shims and autocompletion add to your profile:
  if which pyenv > /dev/null; then eval "$(pyenv init -)"; fi

To use Homebrew's directories rather than ~/.pyenv add to your profile:
  export PYENV_ROOT=/usr/local/var/pyenv
==> Summary
🍺  /usr/local/Cellar/pyenv/20150404: 342 files, 2.8M

バイナリへのパス追加と初期化

tree-no-iMac:~ tree$ vi ~/.bashrc

PYENV_ROOT="${HOME}/.pyenv"
if [ -d "${PYENV_ROOT}" ]; then
    export PATH=${PYENV_ROOT}/bin:$PATH
    eval "$(pyenv init -)"
fi

tree-no-iMac:~ tree$ exec $SHELL -l

pyenvの動作確認

以下でインストール可能なバージョンがずらっと一覧表示されるので、ここでは2.7系の最新版のバージョンを確認しましょう。

tree-no-iMac:~ tree$ pyenv install -l
Available versions:
  2.1.3
  2.2.3
  2.3.7
  2.4
  2.4.1
  2.4.2
  2.4.3
  2.4.4
  2.4.5

pyenvから任意のpythonバージョンをインストールする

この記事を書いた時点の2.7系の最新バージョンは「2.7.10」なので、2.7.10をインストールします。
尚、sphinxはv3系でも動作すると書かれていますが、windowsのチュートリアルの方には以下のように書かれているので、v2.7系の方が安全かと思われます。

Pythonには2系と3系があります。Sphinx-1.2はPython-3.3でも動作します。一般的にはまだPython-2.7の系列が多く使われているので、何かあった場合のサポートをML等で受けやすいと思います。

以降の説明ではPython-2.7を前提として進めます。

http://sphinx-users.jp/gettingstarted/install_windows.html

tree-no-iMac:~ tree$ pyenv install 2.7.10
Downloading readline-6.3.tar.gz...
-> http://ftpmirror.gnu.org/readline/readline-6.3.tar.gz
Installing readline-6.3...
Installed readline-6.3 to /Users/tree/.pyenv/versions/2.7.10

Downloading Python-2.7.10.tgz...
-> https://yyuu.github.io/pythons/eda8ce6eec03e74991abb5384170e7c65fcd7522e409b8e83d7e6372add0f12a
Installing Python-2.7.10...
Installed Python-2.7.10 to /Users/tree/.pyenv/versions/2.7.10

pyenvでv2.7.10 にパスを通す

以下でグローバル設定されます。

tree-no-iMac:~ tree$ pyenv global 2.7.10

pyenvの状態を確認する

tree-no-iMac:~ tree$ pyenv versions
  system
* 2.7.10 (set by /Users/tree/.pyenv/version)

v2.7.10がインストールされていますね。

pythonのバージョンを確認する

tree-no-iMac:~ tree$ python -V
Python 2.7.10

これでmacに初期インストールされたpythonとは別に、pythonをどんどんインストール・アンインストールしていく事ができるようになりました。

別途インストールされたpythonはホームディレクトリに「.pyenv」という隠しフォルダの中にインストールされます。

tree-no-iMac:~ tree$ ll ~/.pyenv/
total 8
drwxr-xr-x  17 tree  staff   578B  6 29 21:42 shims
-rw-r--r--   1 tree  staff     7B  6 29 21:44 version
drwxr-xr-x   3 tree  staff   102B  6 29 21:40 versions

pyenvによってここにpythonがインストールされ、OS標準のpythonのバイナリパスを上書く形でパスが通り、任意のpythonバージョンが使用できるようになります。

pip

pipをインストールする

sphinx、というかpythonのパッケージをインストールする場合はpipを使うと非常に管理が楽になります。

tree-no-iMac:~ tree$ easy_install pip
Searching for pip
Best match: pip 6.1.1
Adding pip 6.1.1 to easy-install.pth file
Installing pip script to /Users/tree/.pyenv/versions/2.7.10/bin
Installing pip3.4 script to /Users/tree/.pyenv/versions/2.7.10/bin
Installing pip3 script to /Users/tree/.pyenv/versions/2.7.10/bin

Using /Users/tree/.pyenv/versions/2.7.10/lib/python2.7/site-packages
Processing dependencies for pip
Finished processing dependencies for pip

コンソールを見ると「Using /Users/tree/.pyenv/versions/2.7.10/lib/python2.7/site-packages」と書かれているので、OS標準のpythonの方ではなく、先ほどインストールしたpyenvの方にインストールされた事が解ります。今後pipでインストールしたパッケージは.pyenv配下にインストールされていきます。

pipを最新版にアップデートする

私がeasy_installでpipをインストールした時は何故か最新版がインストールされず、pipコマンド実行時に以下のinfoが表示されました。

You are using pip version 6.1.1, however version 7.0.3 is available.
You should consider upgrading via the 'pip install --upgrade pip' command.

アップデートコマンドが書いてあるので、この通りに実行して最新版にしましょう。

tree-no-iMac:~ tree$ pip install --upgrade pip
You are using pip version 6.1.1, however version 7.0.3 is available.
You should consider upgrading via the 'pip install --upgrade pip' command.
Collecting pip
  Using cached pip-7.0.3-py2.py3-none-any.whl
Installing collected packages: pip
  Found existing installation: pip 6.1.1
    Uninstalling pip-6.1.1:
      Successfully uninstalled pip-6.1.1
Successfully installed pip-7.0.3

sphinx

pipでsphinxと関連ツールをインストール

tree-no-iMac:~ tree$ pip install sphinx sphinx-autobuild
Collecting sphinx
  Using cached Sphinx-1.3.1-py2.py3-none-any.whl
Collecting sphinx-autobuild
  Downloading sphinx_autobuild-0.5.2-py2-none-any.whl
Requirement already satisfied (use --upgrade to upgrade): sphinx-rtd-theme<0.2,>=0.1 in ./.pyenv/versions/2.7.10/lib/python2.7/site-packages (from sphinx)
Requirement already satisfied (use --upgrade to upgrade): snowballstemmer>=1.1 in ./.pyenv/versions/2.7.10/lib/python2.7/site-packages (from sphinx)
Requirement already satisfied (use --upgrade to upgrade): six>=1.4 in ./.pyenv/versions/2.7.10/lib/python2.7/site-packages (from sphinx)
Requirement already satisfied (use --upgrade to upgrade): Pygments>=2.0 in ./.pyenv/versions/2.7.10/lib/python2.7/site-packages (from sphinx)
Requirement already satisfied (use --upgrade to upgrade): docutils>=0.11 in ./.pyenv/versions/2.7.10/lib/python2.7/site-packages (from sphinx)
Requirement already satisfied (use --upgrade to upgrade): babel>=1.3 in ./.pyenv/versions/2.7.10/lib/python2.7/site-packages (from sphinx)
Requirement already satisfied (use --upgrade to upgrade): Jinja2>=2.3 in ./.pyenv/versions/2.7.10/lib/python2.7/site-packages (from sphinx)
Requirement already satisfied (use --upgrade to upgrade): alabaster<0.8,>=0.7 in ./.pyenv/versions/2.7.10/lib/python2.7/site-packages (from sphinx)
Collecting tornado>=3.2 (from sphinx-autobuild)
  Downloading tornado-4.2.tar.gz (433kB)
    100% |████████████████████████████████| 434kB 1.0MB/s
Collecting PyYAML>=3.10 (from sphinx-autobuild)
  Downloading PyYAML-3.11.tar.gz (248kB)
    100% |████████████████████████████████| 249kB 1.5MB/s
Collecting argh>=0.24.1 (from sphinx-autobuild)
  Downloading argh-0.26.1.tar.gz
Collecting watchdog>=0.7.1 (from sphinx-autobuild)
  Downloading watchdog-0.8.3.tar.gz (83kB)
    100% |████████████████████████████████| 86kB 437kB/s
Collecting livereload>=2.3.0 (from sphinx-autobuild)
  Downloading livereload-2.4.0-py2.py3-none-any.whl
Collecting pathtools>=0.1.2 (from sphinx-autobuild)
  Downloading pathtools-0.1.2.tar.gz
Requirement already satisfied (use --upgrade to upgrade): pytz>=0a in ./.pyenv/versions/2.7.10/lib/python2.7/site-packages (from babel>=1.3->sphinx)
Requirement already satisfied (use --upgrade to upgrade): markupsafe in ./.pyenv/versions/2.7.10/lib/python2.7/site-packages (from Jinja2>=2.3->sphinx)
Collecting backports.ssl-match-hostname (from tornado>=3.2->sphinx-autobuild)
  Downloading backports.ssl_match_hostname-3.4.0.2.tar.gz
Collecting certifi (from tornado>=3.2->sphinx-autobuild)
  Downloading certifi-2015.04.28-py2.py3-none-any.whl (373kB)
    100% |████████████████████████████████| 376kB 1.2MB/s
Installing collected packages: sphinx, backports.ssl-match-hostname, certifi, tornado, PyYAML, argh, pathtools, watchdog, livereload, sphinx-autobuild
  Running setup.py install for backports.ssl-match-hostname
  Running setup.py install for tornado
  Running setup.py install for PyYAML
  Running setup.py install for argh
  Running setup.py install for pathtools
  Running setup.py install for watchdog
Successfully installed PyYAML-3.11 argh-0.26.1 backports.ssl-match-hostname-3.4.0.2 certifi-2015.4.28 livereload-2.4.0 pathtools-0.1.2 sphinx-1.3.1 sphinx-autobuild-0.5.2 tornado-4.2 watchdog-0.8.3

これでsphinxがインストールされました！！
このままではsphinxにパスが通っていない（通っているが反映できていない）ので、以下でシェルを再起動します。

exec $SHELL -l

これでsphinxコマンドが実行可能になります。

sphinxのバージョンを確認

tree-no-iMac:~ tree$ sphinx-quickstart --version
Sphinx v1.3.1

格好いいテーマをインストールする

ansible等で使用されている以下のテーマが格好いいです（個人的に）。

インストール方法は↑に書いてあるので、そちらをご覧下さい。

scaffold的なコマンドでひな形を生成する

詳細はsphinxのチュートリアルを見て欲しいのですが、一応やってみます。

tree-no-iMac:tmp tree$ mkdir /tmp/test && cd $_
tree-no-iMac:tmp tree$ sphinx-quickstart
Welcome to the Sphinx 1.3.1 quickstart utility.

Please enter values for the following settings (just press Enter to
accept a default value, if one is given in brackets).

Enter the root path for documentation.
> Root path for the documentation [.]:

You have two options for placing the build directory for Sphinx output.
Either, you use a directory "_build" within the root path, or you separate
"source" and "build" directories within the root path.
> Separate source and build directories (y/n) [n]: y

Inside the root directory, two more directories will be created; "_templates"
for custom HTML templates and "_static" for custom stylesheets and other static
files. You can enter another prefix (such as ".") to replace the underscore.
> Name prefix for templates and static dir [_]:

The project name will occur in several places in the built documentation.
> Project name: テスト
> Author name(s): tree

Sphinx has the notion of a "version" and a "release" for the
software. Each version can have multiple releases. For example, for
Python the version is something like 2.5 or 3.0, while the release is
something like 2.5.1 or 3.0a1.  If you don't need this dual structure,
just set both to the same value.
> Project version: 1
> Project release [1]: 1

If the documents are to be written in a language other than English,
you can select a language here by its language code. Sphinx will then
translate text that it generates into that language.

For a list of supported codes, see
http://sphinx-doc.org/config.html#confval-language.
> Project language [en]: ja

The file name suffix for source files. Commonly, this is either ".txt"
or ".rst".  Only files with this suffix are considered documents.
> Source file suffix [.rst]:

One document is special in that it is considered the top node of the
"contents tree", that is, it is the root of the hierarchical structure
of the documents. Normally, this is "index", but if your "index"
document is a custom template, you can also set this to another filename.
> Name of your master document (without suffix) [index]:

Sphinx can also add configuration for epub output:
> Do you want to use the epub builder (y/n) [n]: n

Please indicate if you want to use one of the following Sphinx extensions:
> autodoc: automatically insert docstrings from modules (y/n) [n]: y
> doctest: automatically test code snippets in doctest blocks (y/n) [n]: y
> intersphinx: link between Sphinx documentation of different projects (y/n) [n]: y
> todo: write "todo" entries that can be shown or hidden on build (y/n) [n]: y
> coverage: checks for documentation coverage (y/n) [n]: y
> pngmath: include math, rendered as PNG images (y/n) [n]: y
> mathjax: include math, rendered in the browser by MathJax (y/n) [n]: y
Note: pngmath and mathjax cannot be enabled at the same time.
pngmath has been deselected.
> ifconfig: conditional inclusion of content based on config values (y/n) [n]: y
> viewcode: include links to the source code of documented Python objects (y/n) [n]: y

A Makefile and a Windows command file can be generated for you so that you
only have to run e.g. `make html' instead of invoking sphinx-build
directly.
> Create Makefile? (y/n) [y]: y
> Create Windows command file? (y/n) [y]: y

Creating file ./source/conf.py.
Creating file ./source/index.rst.
Creating file ./Makefile.
Creating file ./make.bat.

Finished: An initial directory structure has been created.

You should now populate your master file ./source/index.rst and create other documentation
source files. Use the Makefile to build the docs, like so:
   make builder
where "builder" is one of the supported builders, e.g. html, latex or linkcheck.

生成ウィザード長っ！！最初は長くてちょっとビビリます。

格好いいテーマを反映する

テーマはインストールしただけでは適用されないため、config.pyに設定を反映する必要があります。config.pyは、build/conf.pyにあります。

In your conf.py file:

import sphinx_rtd_theme

html_theme = "sphinx_rtd_theme"

html_theme_path = [sphinx_rtd_theme.get_html_theme_path()]

https://github.com/snide/sphinx_rtd_theme

htmlを出力する

続いてhtmlをビルドします。実行前にcleanしておくと、前回生成したファイルを全削除してからビルドされます。

tree-no-iMac:test tree$ make clean; make html
rm -rf build/*
sphinx-build -b html -d build/doctrees   source build/html
Running Sphinx v1.3.1
making output directory...
loading translations [ja]... done
loading pickled environment... not yet created
loading intersphinx inventory from https://docs.python.org/objects.inv...
building [mo]: targets for 0 po files that are out of date
building [html]: targets for 1 source files that are out of date
updating environment: 1 added, 0 changed, 0 removed
reading sources... [100%] index
looking for now-outdated files... none found
pickling environment... done
checking consistency... done
preparing documents... done
writing output... [100%] index
generating indices... genindex
writing additional pages... search
copying static files... done
copying extra files... done
dumping search index in Japanese (code: ja) ... done
dumping object inventory... done
build succeeded.

Build finished. The HTML pages are in build/html.

htmlを確認する

最後にビルドによって生成された build/html/index.htmlをブラウザ開いてみます。

いい感じにできましたね。後はsphinxのサイトのリファレンスを見れば、大抵の事ができるようになるかと思います。

雑感

sphinxでドキュメントを生成すると、apacheのDocumentRootに配置すればwebで確認できるようになったり、バージョン管理で差分がはっきり解るようになります（excel等だとバイナリになって差分が解らない）。ついでにjsによる簡易検索機能も自動的に付くので、そろそろexcelのAPI仕様書を卒業して、本格的にsphinxに移行すべく勉強中なのです。

チュートリアルが完全に日本語化されているので、英語ワカンネーヨ勢にも優しいと思われるので、是非皆さんもsphinxしましょう！

図解入門よくわかる最新システム開発者のための仕様書の基本と仕組み[第2版] (How‐nual Visual Guide Book)

[改訂第2版] [入門+実践]要求を仕様化する技術・表現する技術 -仕様が書けていますか?

あなたはまだそんな「仕様書」を書いているんですか?