Successfully reported this slideshow.
We use your LinkedIn profile and activity data to personalize ads and to show you more relevant ads. You can change your ad preferences anytime.

Sphinx HTML Theme Hacks

6,415 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!

×