Sphinx HTML Theme Hacks

4,471 views

Published on

Sphinxcon2014でSphinxのHTMLテーマに関して話した際のスライドです。

Published in: Internet

Sphinx HTML Theme Hacks

  1. 1. Sphinx HTML Theme Hacks @shkumagai Oct 26, 2014 SphinxCon 2014
  2. 2. @shkumagai 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
  3. 3. 話すこと • HTMLテーマとは • HTMLテーマの構造 • HTMLテーマの作り方 • パッケージングと配布
  4. 4. HTMLテーマとは
  5. 5. HTMLテーマとは • Sphinxで「make html」を実行して出力される HTMLの見せ方をまとめたもの • 標準で8種類のテーマがある • バージョン0.6から導入された機能 • 1.3からはbizstyleも組み込みとして使えます
  6. 6. 組込みテーマの使い方 • conf.pyに次のように指定して... html_theme = "default" html_theme_options = { "rightsidebar": "true", } • いつものように「make html」するだけ
  7. 7. どう適用されてるか • conf.pyのhtml_theme変数の値を元に、Sphinxの パッケージのthemesディレクトリから該当する テーマのファイル群を取得。 • HTML Builderの初期化のタイミングで、テーマ を初期化。 • HTML生成時にテーマのテンプレートを使ってド キュメントを生成。
  8. 8. HTMLテーマの構造
  9. 9. HTMLテーマの構造 HTML_THEME_PATH/ └ THEME_NAME/ ├ theme.conf ├ layout.html ├   : └ static/ ├ THEME_NAME.css └ THEME_NAME.js
  10. 10. HTML_THEME_PATH • Sphinx HTMLテーマが配置されているパス • デフォルトではインストールされたSphinxパッ ケージの中のthemesディレクトリ • conf.pyを使って任意のパスを指定可能
  11. 11. theme.conf • HTMLテーマの全体の構成を定義するファイル • 他のテーマを継承するか? • Pygmentsのスタイルは何を使うか? • 独自オプションは何があるのか?
  12. 12. layout.html • 実際に表示されるHTMLの元になるテンプレート の土台 • 記述言語はJinja2 • 別テンプレートを継承したり、マクロを定義し たりできる • カスタマイズするとき、ここから読み始めると よい(個人の感想です)
  13. 13. THEME_NAME.css • テーマ専用スタイルを定義するスタイルシート • しかし必須ではない • 静的テンプレートで値の埋め込みもできる
  14. 14. HTMLテーマの作り方
  15. 15. テーマを作る • まず、名前を決める。名前重要。 • ここではsphinxcon14という名前のテーマを作っ てみる。
  16. 16. 用意するもの • theme.conf • layout.html • sphinxcon14.css
  17. 17. ファイルの配置 sphinxcon14/ ├ theme.conf ├ layout.html └ static/ └ sphinxcon14.css
  18. 18. theme.conf • themeとoptionsの2つのセクションで構成されて いる。 • themeセクションは必須。optionsは任意。 • 事実上、HTMLテーマの核。 • 何は無くともtheme.confだけは書く。
  19. 19. theme.conf [theme] inherit = basic stylesheet = sphinxcon14.css pygments_style = friendly
  20. 20. layout.html • doctype, header, footer, relbar, sidebar, content 等のブロックで構成されている。 • ベースのテーマを継承する場合は、継承の宣言 を記述して、変更したい部分だけ上書きしたり、 新規に追加したりする。 • 継承しない場合は、必要なものを全て書く。
  21. 21. 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 %}
  22. 22. sphinxcon14.css • layout.htmlを使って出力されるHTMLに対して 適用するスタイルを記述していく。 • 最初から全部自分で書くよりも、既存のテーマ の記述を真似て少しずつ変更していく方が手を つけやすい。
  23. 23. 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; } :
  24. 24. ファイルの配置(再掲) sphinxcon14/ ├ theme.conf ├ layout.html └ static/ └ sphinxcon14.css
  25. 25. 実際に使ってみる project_root/ ├ conf.py ├ index.rst ├ sphinxcon14/ │ ├ theme.conf │ ├ layout.html │ └ static/ │   └ sphinxcon14.css ├ _build └ _static
  26. 26. conf.py html_theme = "sphinxcon14" html_theme_path = ["."] • html_themeにはテーマの名前(=ディレクトリ の名前)を指定する。 • html_theme_pathは任意のパスを指定する。 conf.pyからの相対パスも指定できる。
  27. 27. パッケージングと配布
  28. 28. 作った、はいいけれど • ドキュメントのプロジェクトを作成する度にテー マのディレクトリをコピーするのはダルい。 • テーマを修正したとき、使っているプロジェク トすべてにさっと反映したい。 • プロジェクトごとに独自の変更をしてしまって 収集がつかなくなる。
  29. 29. 解決方法 • テーマディレクトリの中身をZIPアーカイブする • テーマをパッケージにする
  30. 30. ZIPアーカイブする • HTMLテーマのディレクトリ構造の中身を、その ままZIPでアーカイブ化するだけ(アーカイブに テーマディレクトリ自身は含めない)。 • ドキュメントプロジェクトへの配置方法は、ディ レクトリの時と同じ。
  31. 31. ZIPアーカイブする $ cd sphinxcon14 $ zip -r ../sphinxcon14.zip * $ unzip -Z sphinxcon14.zip ... layout.html ... static/ ... static/sphinxcon14.css ... theme.conf
  32. 32. ZIPアーカイブの利点 • テーマのZIPファイル1つを配布すればテーマの 適用が可能。 • 修正後の再配布も、ディレクトリのまま配布す るよりは簡単。
  33. 33. パッケージにする • HTMLテーマを独立した1つのパッケージに仕立 てる。 • テーマをインストールして、conf.pyでテーマを 指定することでドキュメントにテーマを適用す る。 • 例: sphinxjp.themes.bizstyle
  34. 34. パッケージの利点 • pipやsetuptoolsでインストールできる。 • (実装方法に依存するが)conf.pyの変更箇所が 少なくて済む。 • PyPIに上げれば世界中の人に使ってもらえる機 会が得られる。
  35. 35. 参考資料
  36. 36. • HTML theming support http://sphinx-doc.org/theming.html • Templating http://sphinx-doc.org/templating.html • The build configuration file http://sphinx-doc.org/config.html
  37. 37. • sphinxjp.themes.bizstyle https://bitbucket.org/shkumagai/ sphinxjp.themes.bizstyle • sphinxjp.themes.dotted https://github.com/shkumagai/sphinxjp.themes.dotted • sphinxjp.themes.impressjs https://github.com/shkumagai/ sphinxjp.themes.impressjs
  38. 38. • Sphinxのテーマを継承して体裁をカスタマイズし よう http://heartbeats.jp/hbblog/2013/08/sphinx-customize-theme.html
  39. 39. Any Question?
  40. 40. Have a nice Documentation!

×