作成したテーマを適用する

作成したオリジナルテーマをドキュメントで利用する場合には、3つの方法があります。

1. html_theme_pathに指定したディレクトリにテーマディレクトリ置く

この方法の利点は、ドキュメントを書きながらテーマをどんどん変更していくことができる事です。他のドキュメントに流用する場合、テーマディレクトリをコピーして使う事になります。

ドキュメントのディレクトリに _themes を作成します（他の名前でも構いません）。この下にmythemeを置きます。ディレクトリ構造は以下のようになります:

sphinxdoc/
   +--- conf.py
   +--- *.rst
   +--- _themes/
           +--- mytheme/
           |       +--- theme.conf
           |       +--- layout.html
           |       +--- static/
           +--- other_theme/

次に、conf.pyを以下のように設定します:

html_theme_path = ['_themes']
html_theme = 'mytheme'

2. html_theme_pathに指定したディレクトリにzip圧縮したテーマを置く

この方法の利点は、テーマのzipファイルをサイトなどに公開しておけば、利用者はそのzipファイルをダウンロードして簡単にそのテーマを使うことができる事です。また、テーマディレクトリにzipファイルを同梱してソースコード管理に含めても良いでしょう。

ドキュメントのディレクトリに _themes を作成します（他の名前でも構いません）。この下にmytheme.zipを置きます。ディレクトリ構造は以下のようになります:

sphinxdoc/
   +--- conf.py
   +--- *.rst
   +--- _themes/
           +--- mytheme.zip
           +--- other_theme/

このとき、mytheme.zipの中身は以下の構成にしておきます:

mytheme.zip
   +--- theme.conf
   +--- layout.html
   +--- static/

次に、conf.pyを以下のように設定します:

html_theme_path = ['_themes']
html_theme = 'mytheme'

3. テーマをPythonパッケージ化し、インストール、公開する

この方法の利点は、テーマを環境にインストールできる事です。Sphinxのセットアップ手順などが自動化されている場合、その手順にテーマパッケージのインストールを含めておくことができます。例えば pip install Sphinx mytheme のようにインストールできます。欠点は、テーマパッケージをインストールしていない環境ではドキュメントをビルドできない事です。そのドキュメント特有のテーマであれば、ドキュメントのテーマディレクトリに同梱したほうが良いでしょう。

注釈

この方法はSphinx-1.2以降で使用できます。 Sphinx-1.2以前の場合でも、 sphinxjp.themecore を使えばパッケージ化されたテーマを使用できます。

ここではmythemeというPythonパッケージを作成する例を紹介します。実際には他で使われていない、どんなテーマか分かる名前にするべきでしょう。

ディレクトリ構成は以下のようになります:

mytheme/
   +--- setup.py
   +--- mytheme.py
   +--- MANIFEST.in
   +--- themes/
           +--- mytheme/
                   +--- theme.conf
                   +--- layout.html
                   +--- static/

setup.py:

from setuptools import setup

setup(
    name = 'mytheme',
    version = '1.0.0',
    author = 'yourname',
    author_email = 'yourname@example.com',
    py_modules = ['mytheme'],
    entry_points = {
        'sphinx_themes': [
            'path = mytheme:get_path',
        ],
    },
)

mytheme.py:

from os import path
package_dir = path.dirname(path.abspath(__file__))
template_path = path.join(package_dir, 'themes')

def get_path():
    return template_path

MANIFEST.in:

recursive-include themes *

パッケージを作成します:

$ python setup.py sdist

distディレクトリにmytheme-1.0.0.tar.gz (windowsの場合は.zip)が作成されます。このファイルを他の環境にコピーして pip install mytheme-1.0.0.tar.gz でインストールしたり、任意のサイトから取得出来るようにしておいて pip install http://some.example.com/path/to/mytheme-1.0.0.tar.gz 等でインストールできます。

PyPIにテーマパッケージを登録しておけば、利用したい人は簡単にテーマを使えるようになります。 PyPIに登録する場合は以下のように実行します:

$ python setup.py register sdist upload