Embed Size (px)
DESCRIPTION
Sphinxcon2014でSphinxのHTMLテーマに関して話した際のスライドです。
Citation preview
Sphinx HTML Theme Hacks
@shkumagai Oct 26, 2014
SphinxCon 2014
Ad system backend enginner using Python, Common Lisp, Java, C++... Sphinx-Users.jp member Sphinx HTML Theme Author - sphinxjp.themes.bizstyle - sphinxjp.themes.dotted - sphinxjp.themes.impressjs - sphinxjp.themes.tinkerpress
@shkumagai
話すこと
• HTMLテーマとは
• HTMLテーマの構造
• HTMLテーマの作り方
• パッケージングと配布
HTMLテーマとは
HTMLテーマとは
• Sphinxで「make html」を実行して出力されるHTMLの見せ方をまとめたもの
• 標準で８種類のテーマがある
• バージョン0.6から導入された機能
• 1.3からはbizstyleも組み込みとして使えます
組込みテーマの使い方• conf.pyに次のように指定して...
html_theme = "default" html_theme_options = { "rightsidebar": "true", }
• いつものように「make html」するだけ
どう適用されてるか
• conf.pyのhtml_theme変数の値を元に、Sphinxのパッケージのthemesディレクトリから該当するテーマのファイル群を取得。
• HTML Builderの初期化のタイミングで、テーマを初期化。
• HTML生成時にテーマのテンプレートを使ってドキュメントを生成。
HTMLテーマの構造
HTMLテーマの構造
HTML_THEME_PATH/ └ THEME_NAME/ ├ theme.conf ├ layout.html ├ : └ static/ ├ THEME_NAME.css └ THEME_NAME.js
HTML_THEME_PATH
• Sphinx HTMLテーマが配置されているパス
• デフォルトではインストールされたSphinxパッケージの中のthemesディレクトリ
• conf.pyを使って任意のパスを指定可能
theme.conf
• HTMLテーマの全体の構成を定義するファイル
• 他のテーマを継承するか？
• Pygmentsのスタイルは何を使うか？
• 独自オプションは何があるのか？
layout.html
• 実際に表示されるHTMLの元になるテンプレートの土台
• 記述言語はJinja2
• 別テンプレートを継承したり、マクロを定義したりできる
• カスタマイズするとき、ここから読み始めるとよい（個人の感想です）
THEME_NAME.css
• テーマ専用スタイルを定義するスタイルシート
• しかし必須ではない
• 静的テンプレートで値の埋め込みもできる
HTMLテーマの作り方
テーマを作る
• まず、名前を決める。名前重要。
• ここではsphinxcon14という名前のテーマを作ってみる。
用意するもの
• theme.conf
• layout.html
• sphinxcon14.css
ファイルの配置
sphinxcon14/ ├ theme.conf ├ layout.html └ static/ └ sphinxcon14.css
theme.conf
• themeとoptionsの2つのセクションで構成されている。
• themeセクションは必須。optionsは任意。
• 事実上、HTMLテーマの核。
• 何は無くともtheme.confだけは書く。
theme.conf
[theme] inherit = basic stylesheet = sphinxcon14.css pygments_style = friendly
layout.html
• doctype, header, footer, relbar, sidebar, content 等のブロックで構成されている。
• ベースのテーマを継承する場合は、継承の宣言を記述して、変更したい部分だけ上書きしたり、新規に追加したりする。
• 継承しない場合は、必要なものを全て書く。
layout.html
{% extends "basic/layout.html" %}
{# put the sidebar before the body #} {% block sidebar1 %}{{ sidebar() }}{% endblock %} {% block sidebar2 %}{% endblock %}
{# doctype override #} {%- block doctype %} <!doctype html> {%- endblock %}
sphinxcon14.css
• layout.htmlを使って出力されるHTMLに対して適用するスタイルを記述していく。
• 最初から全部自分で書くよりも、既存のテーマの記述を真似て少しずつ変更していく方が手をつけやすい。
sphinxcon14.css@import url("basic.css");
body { font-family: 'Lucida Grande','Geneva', 'Verdana', sans-serif; font-size: 14px; letter-spacing: -0.01em; line-height: 150%; text-align: center; background-color: white; background-image: url(background_b01.png); color: black; padding: 0;
margin: 0px 40px 0px 40px; } :
ファイルの配置(再掲)
sphinxcon14/ ├ theme.conf ├ layout.html └ static/ └ sphinxcon14.css
実際に使ってみるproject_root/ ├ conf.py ├ index.rst ├ sphinxcon14/ │ ├ theme.conf │ ├ layout.html │ └ static/ │ └ sphinxcon14.css ├ _build └ _static
conf.py
html_theme = "sphinxcon14"
html_theme_path = ["."]
• html_themeにはテーマの名前（=ディレクトリの名前）を指定する。
• html_theme_pathは任意のパスを指定する。conf.pyからの相対パスも指定できる。
パッケージングと配布
作った、はいいけれど
• ドキュメントのプロジェクトを作成する度にテーマのディレクトリをコピーするのはダルい。
• テーマを修正したとき、使っているプロジェクトすべてにさっと反映したい。
• プロジェクトごとに独自の変更をしてしまって収集がつかなくなる。
解決方法
• テーマディレクトリの中身をZIPアーカイブする
• テーマをパッケージにする
ZIPアーカイブする
• HTMLテーマのディレクトリ構造の中身を、そのままZIPでアーカイブ化するだけ（アーカイブにテーマディレクトリ自身は含めない）。
• ドキュメントプロジェクトへの配置方法は、ディレクトリの時と同じ。
ZIPアーカイブする
$ cd sphinxcon14 $ zip -r ../sphinxcon14.zip *
$ unzip -Z sphinxcon14.zip ... layout.html ... static/ ... static/sphinxcon14.css ... theme.conf
ZIPアーカイブの利点
• テーマのZIPファイル１つを配布すればテーマの適用が可能。
• 修正後の再配布も、ディレクトリのまま配布するよりは簡単。
パッケージにする
• HTMLテーマを独立した１つのパッケージに仕立てる。
• テーマをインストールして、conf.pyでテーマを指定することでドキュメントにテーマを適用する。
• 例： sphinxjp.themes.bizstyle
パッケージの利点
• pipやsetuptoolsでインストールできる。
• （実装方法に依存するが）conf.pyの変更箇所が少なくて済む。
• PyPIに上げれば世界中の人に使ってもらえる機会が得られる。
参考資料
• HTML theming supporthttp://sphinx-doc.org/theming.html
• Templatinghttp://sphinx-doc.org/templating.html
• The build configuration filehttp://sphinx-doc.org/config.html
• sphinxjp.themes.bizstylehttps://bitbucket.org/shkumagai/sphinxjp.themes.bizstyle
• sphinxjp.themes.dotted https://github.com/shkumagai/sphinxjp.themes.dotted
• sphinxjp.themes.impressjshttps://github.com/shkumagai/
sphinxjp.themes.impressjs
• Sphinxのテーマを継承して体裁をカスタマイズしようhttp://heartbeats.jp/hbblog/2013/08/sphinx-customize-theme.html
Any Question?
Have a nice Documentation!
![Python Maintenance EP...@HYNEK tox.ini [testenv:docs] basepython = python3.7 extras = docs commands = sphinx-build -W -b html -d {envtmpdir}/doctrees docs docs/_build/html @HYNEKHYNEK](https://img.pdfslide.us/doc/110x75/5f0dfe9e7e708231d43d194e/python-maintenance-ep-hynek-toxini-testenvdocs-basepython-python37-extras.jpg)
