テーマの変更

概要

Sphinxには、標準で以下の9つのテーマ[1]が用意されています。

  • default
  • basic
  • sphinxdoc
  • scrolls
  • agogo
  • nature
  • pyramid
  • haiku
  • traditional
  • epub

まずは、標準のテーマを他のテーマへ変更する方法を確認しましょう。詳細については公式ドキュメントを参照して下さい。

手順

テーマを変更するには、conf.pyの以下の部分を編集します。

# -- Options for HTML output ---------------------------------------------------

# The theme to use for HTML and HTML Help pages.  See the documentation for
# a list of builtin themes.
#html_theme = 'default'
html_theme = 'default'

# 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 = []

標準では、html_themeにはdefaultが指定され、テーマのパスを指定する項目html_theme_pathはコメントアウトされています。

conf.pyhtml_themeの値を、組込みテーマから選択して指定すれば、指定したテーマに変更する事が出来ます。以下の例では、sphinxdocテーマを指定しています。

# The theme to use for HTML and HTML Help pages.  Major themes that come with
# Sphinx are currently 'default' and 'sphinxdoc'.
html_theme = 'sphinxdoc'

conf.pyを書き換えた後、make htmlを実行すれば指定したテーマのhtmlが出力されます。

組み込みテーマの紹介

default

下記がdefaultテーマです。defaultテーマはsphinx-quickstartコマンドでプロジェクトを生成した直後に設定されているテーマです。

../../_images/default.png

basic

../../_images/basic.png

sphinxdoc

../../_images/sphinxdoc.png

scrolls

../../_images/scrolls.png

agogo

../../_images/agogo.png

nature

../../_images/nature.png

pyramid

../../_images/pyramid.png

haiku

../../_images/haiku.png

traditional

../../_images/traditional.png

epub

../../_images/epub.png

サードパーティ製テーマの紹介

標準で提供されているテーマの他に、有志によって様々なテーマが公開されています。ここで紹介するサードパーティ製のテーマはPythonのパッケージ管理ツールeasy_installpipを用いてインストールします。

ちなみに

Sphinx 1.2でsphinxjp.themecoreの機能が標準に取り込まれました。そのため、1.2以降をお使いの場合はhtml_themeを書き換えるだけでテーマの変更が可能です。1.2より前をお使いの場合は、sphinxjp.themecoreをインストールしたうえで、以下の行をconf.pyに追加してください。

extensions = ['sphinxjp.themecore']

sphinxjp.themes.bizstyle

http://pypi.python.org/pypi/sphinxjp.themes.bizstyle/

../../_images/bizstyle.png
  • インストール方法例:

    easy_install sphinxjp.themes.bizstyle
    
  • conf.pyの書き換え:

    html_theme = 'bizstyle'
    
    # 下記オプションでバックグラウンドの色を変更する事が可能です。※必須ではありません
    html_theme_options = {'maincolor' : "#696969"}
    

sphinxjp.themes.dotted

http://pypi.python.org/pypi/sphinxjp.themes.dotted/

../../_images/dotted.png
  • インストール方法例:

    easy_install sphinxjp.themes.dotted
    
  • conf.pyの書き換え:

    html_theme = 'dotted'
    

sphinxjp.themes.sphinxjp

http://pypi.python.org/pypi/sphinxjp.themes.sphinxjp/

../../_images/sphinxjp.png
  • インストール方法例:

    easy_install sphinxjp.themes.sphinxjp
    
  • conf.pyの書き換え:

    html_theme = 'sphinxjp'
    

sphinxjp.themes.trstyle

http://pypi.python.org/pypi/sphinxjp.themes.trstyle/

../../_images/trstyle.png
  • インストール方法例:

    easy_install sphinxjp.themes.trstyle
    
  • conf.pyの書き換え:

    html_theme = 'trstyle'
    

sphinxjp.themes.basicstrap

https://pypi.python.org/pypi/sphinxjp.themes.basicstrap/

../../_images/default1.png
  • インストール方法例:

    easy_install sphinxjp.themes.basicstrap
    
  • conf.pyの書き換え:

    html_theme = 'basicstrap'
    
    # 下記オプションで内部テーマを変更する事が可能です。※必須ではありません
    # また、これ以外にも細かい設定変更が可能です。
    html_theme_options = {
        'inner_theme': True,
        'inner_theme_name': 'bootswatch-amelia',
    }
    

また、細かく設定を変更すれば、フォントサイズの変更やGoogle Web Fontsの利用、Bootswatchの各種テーマの利用ができます。詳しくは、ドキュメントや作者ブログ記事(0.2.0リリース/0.3.0リリース)もご覧ください。

以下、利用できるテーマの一覧です。

bootswatch-amelia bootswatch-cerulean bootswatch-cosmo
bootswatch-amelia
bootswatch-cerulean
bootswatch-cosmo
bootswatch-cyborg bootswatch-flatly bootswatch-journal
bootswatch-cyborg
bootswatch-flatly
bootswatch-journal
bootswatch-readable bootswatch-simplex bootswatch-slate
bootswatch-readable
bootswatch-simplex
bootswatch-slate
bootswatch-spacelab bootswatch-united  
bootswatch-spacelab
bootswatch-united
 
bootswatch-spruce bootswatch-superhero geo-bootstrap
bootswatch-spruce
bootswatch-superhero
geo-bootstrap

mitsuhiko / flask-sphinx-themes

https://github.com/mitsuhiko/flask-sphinx-themes

../../_images/flask.png
  • インストール方法例

    このテーマは手動でインストールが必要です。

    1. githubからソースを取得する:

      git clone https://github.com/mitsuhiko/flask-sphinx-themes.git
      

      gitについて良くわからない場合は、githubの「Download ZIP」のボタンからダウンロードしても構いません。

    2. sourceフォルダ直下に「_themes」フォルダを作成し、以下のように配置する。(flask以外にflask_smallもあり):

      source/_themes/flask/theme.conf
      
  • conf.pyの書き換え:

    # 出来るだけ先頭に以下を記述する。
    sys.path.append(os.path.abspath('_themes'))
    
    html_theme = 'flask'
    html_theme_path = ['_themes']
    

詳しくは、githubページのREADMEをご覧ください。

Pylons / pylons_sphinx_theme

https://github.com/Pylons/pylons_sphinx_theme

../../_images/pylons.png
  • インストール方法例

    このテーマは手動でインストールが必要です。

    1. githubからソースを取得する:

      git clone https://github.com/Pylons/pylons_sphinx_theme.git
      

      gitについて良くわからない場合は、githubの「Download ZIP」のボタンからダウンロードしても構いません。

    2. sourceフォルダ直下に「_themes」フォルダを作成し、以下のように配置する。(pylons以外にpylonsfwやpyramidもあり)

      source/_themes/pylons/theme.conf

  • conf.pyの書き換え:

    # 出来るだけ先頭に以下を記述する。
    sys.path.append(os.path.abspath('_themes'))
    
    html_theme = 'pylons'
    html_theme_path = ['_themes']
    

詳しくは、githubページのREADMEをご覧ください。

kellycreativetech / proBlue

https://github.com/kellycreativetech/proBlue

../../_images/proBlue.png
  • インストール方法例

    このテーマは手動でインストールが必要です。

    1. githubからソースを取得する:

      git clone https://github.com/kellycreativetech/proBlue.git
      

      gitについて良くわからない場合は、githubの「Download ZIP」のボタンからダウンロードしても構いません。

    2. sourceフォルダ直下に「_themes」フォルダを作成し、以下のように配置する。(proBlueフォルダは自分で作る)

      source/_themes/proBlue/theme.conf

  • conf.pyの書き換え:

    # 出来るだけ先頭に以下を記述する。
    sys.path.append(os.path.abspath('_themes'))
    
    html_theme = 'proBlue'
    html_theme_path = ['_themes']
    

詳しくは、githubページのREADMEをご覧ください。

脚注

[1]バージョン1.2現在。