いろいろ調べてる時、なんかよくAPIドキュメントでこういう感じ(↓)のデザインのドキュメントを見ると思ってたんですけど、 sphinx_rtd_themeっていうSphinxのテーマでした。知らんかった。
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
おおお!!
編集したら自動的にビルドできるようにする
ここからはおまけです。
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自体だったりにこういう仕組みは既にあるのかもしれないんですが、同じ方法で実行している人も居るし、そんなもんなんじゃないかなと思ったりはしてます。
解決方法の一つとして。