本稿ではPythonモジュール"Sphinx"に関する
- インストール方法
- プロジェクト作成方法
- 標準テーマ変更方法
- 外部テーマ(Bootswatch)変更方法
について解説します。
Sphinxに関する詳しい解説などは以下サイトを御覧ください。
Sphinx日本ユーザー協会
使用環境
- Mac OSX El Capitan
- Python3.5.1
- VirtualEnv
今回は仮想環境を作成しインストールしていますが、
この手順は各自の仮想環境モジュールをご使用いただくか、こだわりがなければ不要です。
インストール方法
任意の場所に仮想環境を作成し、起動します。
$ mkdir Sphinx
$ virtualenv --no-site-packages Sphinx
$ cd Sphinx
$ source bin/activate
(Sphinx)$
続いて、Sphinxモジュールをpipを用いてインストールします。
(Sphinx)$ pip install sphinx
ここまでで、Sphinxのインストールは完了です。
プロジェクト作成
任意の場所にプロジェクト専用のフォルダを作成し、
その中でsphinx-quickstartコマンドを実行します。
(Sphinx)$ mkdir MyProject
(Sphinx)$ cd MyProject
(Sphinx)$ sphinx-quickstart
コマンド実行すると、あらゆるオプションに関して質問されますが、基本Enterキーを押しておけば問題ありませんが、
- ProjectName
- Author Name
- Version
の3つのみ入力必須項目となっていますので、適切に入力してください。
1項目言語設定がありますが、日本語にする場合はjaと入力し続行してください。
プロジェクト作成完了後
(Sphinx)$ make html
を実行すると、カレントディレクトリの_build/html内にHTMLが生成されます。
_build/html/index.htmlをブラウザで表示すると、ドキュメントが生成されていることがわかります。
標準テーマの変更
テーマ変更に関する設定は、プロジェクトフォルダ(今回はMyProject)内にある
conf.pyで行います。
html_theme = 'default'
の文字列部分を変更することで標準テーマを変更することができます。
変更後は忘れずに
(Sphinx)$ make html
を行いましょう。
標準テーマは以下の9つがあります。
- default
- basic
- sphinxdoc
- scrolls
- agogo
- nature
- pyramid
- haiku
- traditional
- epub
使用できる標準テーマイメージは以下サイトに掲載されています。
標準テーマ集
外部テーマの使用
Sphinxでは、外部テーマを使用することも可能です。
今回はBootswatchテーマを使用して解説します。
Bootswatch
・ Bootswatchのインストール
引き続き仮想環境内で作業します。
(Sphinx)$ pip install shpinx_bootstrap_theme
・ BootswatchテーマのSphinxへの設定
これについても、プロジェクトフォルダ内のconf.pyで設定します。
まずはじめに、conf.pyの先頭行でモジュールをインポートします。
コメントはつけないよう気をつけてください。
import sphinx_bootstrap_theme
引き続き、テーマの保存されているディレクトリ
及びテーマ名を設定します。
html_theme = 'bootstrap'
html_theme_path = ['../lib/python3.5/site-packages/sphinx_bootstrap_theme']
Bootwatch公式ドキュメンテーションではhtml_theme_pathの設定に専用の関数が用意されているとの記載がありましたが、私の環境ではエラーが出たため、モジュールへの相対パスで記載しています
追記:yuntas様ご指摘
conf.py の以下コメントアウトを解除すれば解決するようです。
import os
import sys
sys.path.insert(0, os.path.abspath('.'))
...
html_theme_path = sphinx_bootstrap_theme.get_html_theme_path()
次に、どのBootwatchテーマを使用するかを先程のコードの真下に指定します。
テーマの種類についてはこちらを参照ください。
Bootswatch
html_theme_options = {'bootswatch_theme': "cosmo"}
こちらも変更後は忘れずに
(Sphinx)$ make html
を行いましょう。
以上で、外部テーマの設定が終了しました。