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