Spica*

プログラミングの話。

MacでSphinxインストールしてモダンなsphinx_rtd_theme使ってみたのと簡易自動ビルド

いろいろ調べてる時、なんかよくAPIドキュメントでこういう感じ(↓)のデザインのドキュメントを見ると思ってたんですけど、 sphinx_rtd_themeっていうSphinxのテーマでした。知らんかった。

f:id:esperia:20150704100936p:plain

Powerline Documentation

Sphinxっていうのは、ドキュメントを掻くためのツールです。一言で言うと静的なWikiみたいな感じ。reStructuredTextという記法でドキュメントを書いた後ビルドを行うと、静的なHTMLドキュメントが生成されます。"静的"なのが特徴で、PHPみたいなサーバサイドで動くソフトウェアとか入ってなくても、index.htmlをダブルクリックするだけでドキュメントが表示されます。簡単にいい感じのドキュメント作ろうと思うと選択肢としてはとっても良いものです!

で、ちょっと以前作ったスクリプトもなんとなく使うことが多いので、ブログに収めておこうかと思いました。

Sphinxのインストール

# Homebrew(http://brew.sh/)はあらかじめ入れておく。

# pythonとpipのインストール
brew update
brew install python

# Sphinxのインストール
pip install sphinx

# sphinx_rtd_themeのインストール
#pip install sphinx_rtd_theme

僕だけかもしれないんですが、Googleの検索結果でsphinx-users.jpのドキュメントが一番上に来ます。ただこっちは既に古くなっているみたいで、今はsphinx-docs.orgの方が最新です。日本語はこっちsphinx-users.jpではeasy_installを使ったインストールが解説されていますが、現在はpipの方がベターなパッケージ管理ツールなので、こちらを使います。

現在、pip install sphinx_rtd_themeは、sphinxの依存関係に含まれているので、pipでsphinx入れただけでsphinx_rtd_themeもインストールされます。

プロジェクトの作成とビルド

# フォルダを作ってその中に入る
mkdir docs
cd docs

# 実行
sphinx-quickstart

対話形式でたくさん質問される。でも基本全部デフォルト(訊かれてもEnterキー押しておく)で大丈夫。必須項目だけ載せておく

The project name will occur in several places in the built documentation.
> Project name:
my-delicious-docs # 入力

> Author name(s):
esperia # 入力

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:
0.1.0 # 入力

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

テーマを入れ替えてビルド

conf.pyを開いて、以下の様に修正。

# ...省略...

import sys
import os
import shlex
import sphinx_rtd_theme # 追加

# ...省略...

# The theme to use for HTML and HTML Help pages.  See the documentation for
# a list of builtin themes.
#html_theme = 'alabaster' # コメントアウト
html_theme = 'sphinx_rtd_theme' # 追加

# 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 = [sphinx_rtd_theme.get_html_theme_path()] # 編集

そして、下記のコマンドを入力してビルド!

# ビルド
make html

f:id:esperia:20150704131016p:plain

おおお!!

編集したら自動的にビルドできるようにする

ここからはおまけです。 Sphinxってビルドいちいちめんどくさいんですよね。編集したらビルド、編集したらビルド…を繰り返すので。 で、結構前なんですが、node.jsとgruntを使って、編集するファイルを監視し、ファイルが変更されたら自動的にmake htmlを実行する方法があるので、こちらもせっかくなので日記に記します。

まずはnode.jsをインストールします。

# nodebrewのインストール(https://github.com/hokaccha/nodebrew)
curl -L git.io/nodebrew | perl - setup
echo "export PATH=$HOME/.nodebrew/current/bin:$PATH" >> ~/.bashrc

# node.jsとnpmインストール
nodebrew install-binary latest
nodebrew use latest
npm -v

npm initを入力してpackage.jsonを作成します。いろいろ訊かれますが、全部EnterキーでOKです。

npm init

続けてgruntとgrunt-contrib-watchプラグインをインストールします。

npm install -g grunt-cli
npm install grunt --save-dev
npm install grunt-contrib-watch --save-dev

スクリプトをダウンロードして、実行します。

# https://gist.github.com/esperia/698c089861ab9d246940 のスクリプト
curl -O -L https://gist.githubusercontent.com/esperia/698c089861ab9d246940/raw/2054d7f285e9636fb48bf0ff388f9d07a578252d/Gruntfile.js

# ファイルの変更を監視
grunt watch

この状態で各種*.rstを編集すると、自動的にmake htmlが実行されます! sphinx自体だったりにこういう仕組みは既にあるのかもしれないんですが、同じ方法で実行している人も居るし、そんなもんなんじゃないかなと思ったりはしてます。 解決方法の一つとして。