Sphinx Advent Calendar 16日目

sphinx log

Sphinx Advent Calendar 2012 - connpass の 16 日目です。
昨日は @cointoss1973 さんの pandoc で Redmine の Wiki を Sphinx に変換しよう - secretbase.log でした。

今日のハナシ

5 日目を担当された @togakushi さんが題材にしている Sphinx HTML テーマを、自分も取り上げてみようと思います。

HTML テーマ事始め - 日本語版

今年 9 月の SphinxCon JP 2012 で Sphinx HTML テーマを題材に発表をしたのですが、その発表の追補という位置づけです。

自作 HTML テーマを zip で配布する

SphinxCon JP 2012 の発表では自作のテーマのディレクトリ構成を提示して、そのディレクトリを直接指定してテーマを読み込ませる、という手法を紹介したわけですが、この手法には「複数人数で同じテーマを使いたい場合に、面倒くさい」という短所があります。

テーマを一つのディレクトリとして構成しているので、そのディレクトリをまるごと共用しないといけないわけです。ちょっとこれはイケてないですよね。

はて、どうしたものか... というところですが、 Sphinx の公式ドキュメントには以下のような記述があります :

If the theme does not come with Sphinx, it can be in two forms: either a directory (containing theme.conf and other needed files), or a zip file with the same contents.

テーマが Sphinx に付属していない場合、次の２つの方法で指定できます: ディレクトリ（ ``theme.conf`` とその他の必要なファイルを含む）か、同じ内容の zip ファイルのいずれか、です。

ということで、ここでは HTML テーマ を zip ファイルにまとめる方法を紹介したいと思います。

ちょっと復習

さて、自作の HTML テーマということですが、どうやって作ればいいのか分からない方向けの説明も兼ねて、ちょっと復習してみましょう。実際にここに示すように作ってみて、動作確認をすると理解が進むと思うので環境が用意できる方は、手を動かしながら読んでいくと良いと思います。
もちろん、既にご存知の方はこの節は読み飛ばして頂いて結構です。

まず、Sphinx の HTML テーマは以下のような構成になっています。


  + theme.conf
  + template ファイル (例えば layout.html など。必要な場合のみ)
  + static/
      + CSS ファイル
      + 画像ファイル (必要な場合のみ)

このうち、絶対に必要なものは一番上にある theme.conf だけです。その下にある layout.html や CSS ファイルは変更を加える必要がないときには、テーマに含める必要はありません。

ここで仮に mytheme というテーマを作成すると仮定して、構成を見てみることにします。適当なワーキングディレクトリに mytheme というディレクトリを作成し、その下に theme.conf を作成してみましょう :

$ mkdir mytheme
$ cd mytheme
$ vim theme.conf

theme.conf の中身は次のようにします。

[theme]
inherit = sphinxdoc
stylesheet = mytheme.conf
pygments_style = friendly

次に static ディレクトリを作成して、その下に mytheme.css を作成します :

$ mkdir static
$ cd static
$ vim mytheme.css

mytheme.css の中身は次のようにします。変更したスタイルが適用されていることが確認しやすいように、背景色だけ変更しておきましょう :

@import url("sphinxdoc.css");

body {
    background-color: #dbd0e6;
}

ここまでで mytheme ディレクトリの下は次のような構成になっているはずです :

mytheme
  + theme.conf
  + static
      + mytheme.css

そうしたら mytheme ディレクトリの直下に戻って、次の手順で zip ファイルを作成してみましょう :

$ zip -r mytheme.zip *
$ ls -F
mytheme.zip static/     theme.conf

zip ファイルができあがりましたね。そうしたら作成したテーマを適用したい Sphinx のドキュメントプロジェクトディレクトリの中で conf.py と同じディレクトリに mytheme.zip を置き、 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 = 'mytheme'

# Add any paths that contain custom themes here, relative to this directory.
html_theme_path = ["."]

ポイントとして html_theme_path の値は conf.py からの相対パスを指定します。コメント部分にも書いてありますが、注意しましょう。

あとはいつものとおり、 make html を叩くだけです。

どうでしょう、背景色が薄紫色に変わった sphinxdoc テーマのページが表示されたでしょうか？上手く表示できたら成功です。
逆に make html を実行した後にエラーメッセージが出てしまっている場合は、テーマがうまく読み込めていない可能性があります。この記事のコードスニペット部分と手元のコードをよく見比べてみてください（そしてもしタイポを発見した場合にはコメントをして頂けると助かります）。

おわりに

Sphinx HTML テーマは、ご覧頂いたような手順で簡単に継承・上書きして、配布することができます。しかも HTML テーマのカスタマイズに関して言えば、大掛かりな構造の変更でない限りは Python の知識が無くてもなんとかなります*1。

もし自作のテーマを手元に抱えたままにしているのであれば、この方法を使って他の人にも配ってみてください。

明日は @kashew_nuts さんです。よろしくお願いします。

参考

*1:もちろん、Sphinx が吐く HTML は御世辞にもキレイとは言えないのと、継承元のテーマで適用しているスタイルとの兼ね合いがあるので意図した通りにスタイルを変更するのはなかなか難しいかも知れませんが、そこは Try and Error で慣れていく必要がある部分だと思っています。

PySpa アドベントカレンダー 2日目

python

PySpaアドベントカレンダー - connpass の 2 日目です。

技術的にも人間的にもコレといって語れるようなネタを持っているわけでもなく、さてどうしたものかと考えていたのですが、どうにも思いつかないので困り果ててしまったので、ここ 2 年くらいの自分を PySpa 周辺のあたりに絡めて振り返ってみようかと思います。

そもそもの話

初めて、にこういったコミュニティベースでの人との繋がりの輪の中で活動をするなったのは「Sphinx + 翻訳ハッカソン」というイベントがきっかけでした。2010年の夏ごろだったかと思います。
そのときの会場は、いま自分が在籍している会社の会議室でした。

Sphinx翻訳ハッカソン(2010/09/05) — Python製ドキュメンテーションビルダー、Sphinxの日本ユーザ会

当時の自分は某巨大ECサイトの検索エンジンのお守りをしていて、コードを書くと言えばシステムの運用やメンテナンスにつかう BASH や Perl スクリプトの作成や改修などが主だったと記憶しています。

あまり目新しいネタに触れる機会がないままだったこと、検索エンジンのことをもっとキチンと理解したいと思っていたこともあって、一人でいろいろと調べているうちに Python や Sphinx のことを知りました。

また検索に関する日本語の文献が少なくて、結果として洋書を読む機会が多かったこともあって、自分ひとりのためではあるものの翻訳をやってみようと思い立ち、ひとりで洋書のペーパーバックを買って地道に翻訳を進めてみたりもしていました。

そんな時に「Sphinx + 翻訳ハッカソン」の存在を知ったわけです。

それまでそういった活動の場面に接することもなかったので、初参加のときはかなり躊躇しながらの参加でしたが、いま思うとあそこで一歩踏み出していなかったらいまこの自分は居なかったわけですから、自分に取ってのターニングポイントはこの時だったのかなと、いまさらながらに思いますね。

それから

さて、無事（？）にイベントへの初参加を果たした後、そこで知り合った人たちに巻き込まれたのか、自分から突っ込んでいっただけなのかは判然としませんが、徐々に Sphinx-Users.jp の活動に関わるようになっていき、年が明けました。同時に、自分はこの頃になって初めて PySpa というイベントがあること知りました。

Python Hack-a-thon（現: PyFes）で @voluntas に会ったのもその頃だったと思います。その時は、彼が自分の近くに座っていた別の人と話をしていたところに横から割り込む格好になって二言三言だけ言葉を交わした程度だっただけでしたが。

Python Hack-a-thon 2011.02 : ATND

Python 温泉には、その年の11月（第10回。定期開催では最終回）で初めて参加しました。

その前の第 9 回のときは、常連優先ということもあって選外となり、参加ができなかったので、夜中に一人で Twitter のタイムラインの盛り上がりを眺めていたことを覚えています。

またこの時、自分は既に前職を辞めていて、次の仕事を始めるまでのインターバル期間のような状態でした。生来あまり計画的な方ではないので思いのほか自由になる金が手元に無くて、参加費用をなんとか捻出しての参加でした。

初めて参加した PySpa は、人づてに聞いていた話の通りでもあり、想像と違っていた部分もありでしたが、とても新鮮な感覚でした。

技術の話にしてもそれ以外の話題にしてもその話題（？）に通じた人が居て、これまた異なる意見を持つ人が居て、時には意見を戦わせてみたり相手の話に引きこまれてみたり、他方では我関せずとばかり自分の課題に打ち込む人あり、と各人が思い思いの過ごし方で "場" を共有することの様式美を見た思いがします。

個人的には「食事は全員で揃って食べる」というルールが、一番気に入ってます。

そして、最近の話

前職を退職した後に、およそ 1 ヶ月のインターバルを終えていまの仕事に就いたのは、ちょうど 1 年前の 12 月のことでした。

仕事では主に Python と Erlang と Shell Script、そして reStructuredTextを書いています。
「製品の機能開発をする」、「テストを書く」、「ドキュメントを書く」という、およそソフトウェア製品開発の基本的な作業を粛々と行うことが、主に自分の担っている役どころというところでしょうか。

プライベートでは Sphinx-users.jp の副会長などを努めることになったり、ときどき HTML テーマを作ってみたり、SphinxCon 2011 で発表をしてみたり、オープンソースのプロダクトに Pull Request を出してみたりということをちまちまとやっています。

まとめ

さて、締まらない感じで来てしまいましたが、まとめです。

前職を辞め、職場を変えてからもう 1 年が経ちます。時折会う前職の同僚・友人などから「顔色がよくなった」と言われることが幾度かありました。辞めた当時はムリをしていたつもりはカケラもなかった自分ですが、見る人からみれば、その目にはそう映っていたのかも知れません。

そして今、自分はかつての自分とは異なった場所に居て、異なった働き方をしています。比較的早い時間に帰って、自分の好きな事に使える時間をより多く確保出来るようにもなりました。

これはもちろん PySpa に限った話ではないのですが、自分が今このように働いていられるのは、ここ 2 年やそこらの内で関わった人たちから頂いた有形・無形の「何か」によって支えられてきた事と無関係ではないと思います。

PySpa ならびに Sphinx, Python 関連でお世話になっている皆さんには、本当に感謝しています。ちょっとやそっとでは到底返しきれないくらい、頂いたものがたくさんあると思っています。

生来、ゆるい人間なのでどこまで出来るかは分かりませんが、自分が恩を受けた分は何らかの形で返して行けたらと思います。


では、明日は @tokibito さんです。よろしくお願いします！

sphinxjp.themes.bizstyle 0.1.5 リリースしました。

log python sphinx document

序

もっと間が空いているかと思いきや、２ヶ月とちょっと前に書いていたのを久しぶりに見て認識するという放置っぷりに、やや引く。。。

sphinxjp.themes.bizstyle 0.1.5 リリース

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

しばらくもやもやと考えていたことを実行に移してみた、という意味でのアップデートは一つ前のリリース（0.1.4）でやっていたので、そこからの大きな変更はありません。
今回のリリースの目的は頂いた pull request をHEADにマージする、という意味合いが大きいです。

pull request を頂いた @hokorobi さん、ありがとうございます。

結

やってみようと思っていたTODOを一つ片付けられたので、ちょっと一息つけました。

もう少し突っ込んだ内容で新しいテーマに挑戦してみようと思います。

sphinxjp.themes.impressjs 0.1.2 リリースしました。

log sphinx python document

序

前回の更新からだいぶ間が空いてしまいました。Python界の根無し草です。
厳しめの寒さが少しずつ緩み始めた昨今ですが、いかがお過ごしでしょうか?

sphinxjp.themes.impressjs 0.1.2 リリース

sphinxjp.themes.impressjs · PyPI

毎度おなじみ、といった体の記事になってきました。Sphinx用テーマのアップデートリリースです。

このテーマはCSS3とJavascriptを使ったHTMLによるプレゼンテーションを実現するものです。最初のリリースの際は少しバタバタとしていたので、このブログでの紹介をしないままになっていました。

このテーマで利用させてもらっている「Impressjs」は「Prezi」にインスピレーションを受けて作成されたもので、非常にインパクトのあるプレゼンテーションを作成する事が出来るものです。

最初に「Impressjs」のサンプルを見たとき、「これ、Sphinxで作れたら面白いんじゃないか?」と思ったもののなかなか手を付ける事が出来ずに居たのですが、2012年02月の初旬にあったPython mini Hack-a-thonの雪山合宿でなんとかカタチにすることが出来ました。

興味を持たれた方はPyPIの方から入手して使ってみてください。

結

自分が思っている以上に周囲の人からは「Sphinxのテーマの人」という認知を得ているようで嬉しい反面、もうちょっと別の部分でも認知してもらえるようにしたいと思う、今日この頃。

欲張っても仕方ないのでアレですが、ぼちぼちやって行きます。

なお、「こんなテーマが欲しい」とか「テーマってどうやって作るの？」という質問があればお気軽にご相談ください。

sphinxjp.themes.dotted 0.1.1 リリースしました。

log python sphinx document

序

相変わらず、ゆるいペースでもぞもぞと活動しています。どうも、Python界の流浪人です。朝夕の冷え込みが少しずつ秋の深まりを感じさせる季節になってきましたね。風邪などひいていませんでしょうか?

sphinxjp.themes.dotted 0.1.1 リリース

sphinxjp.themes.dotted · PyPI

さて。タイトルの通りなんですが、先日リリースした sphinxjp.themes.dotted の更新を行いました。内容はPyPIのヒストリに記載しているとおり、

  • サイドバーの表示/非表示の切り替え
  • サイドバー表示位置(左/右)の切り替え


です。

一つ目の方は enablesidebar 、二つ目の方は rightsidebar というオプション名でTrue/Falseを引数に取ります。conf.pyの中のhtml_theme_optionsに、以下のように値を渡して設定します。

html_theme_options = {'slidetoc': False,
                      'enablesidebar': True,
                      'rightsidebar': False,}

当初はサイドバー無しのデザインで通すつもりで居たのですが、Twitter上で「サイドバーは必須だ」といったやり取りを目にして、やはり「在ってもいいのかも」と思い直してサイドバーを使えるようにしてみました。とはいえ、単純に追加しただけではbizstyleと大差が無いので、今回は「サイドバーの表示/非表示を切り替えできるとかいいかも」と考えてトライしてみました。

SphinxのHTMLレイアウトは、テンプレートエンジンにjinja2を使っているので基本的なルールが分かれば結構柔軟にいじることが出来ます。CSSの方も「条件分岐を使って不要な定義を書き出さない」という記述ができるので、動的にスタイルの定義を切り替える事も出来ますしなかなかどうして便利です。

結

今回は自分の中からではなく外部からきっかけを頂くことで手を動かしたのですが、こういう風に「こうして欲しい！」とか「ああだったらイイのに！」という働きかけは何かを作る側の背中を押す効果があるのだな、としみじみ思いました。

デザイナーではないので見た目のセンス的にはアレですが、使って頂ければ幸いです。

sphinxjp.themes.dotted 0.1.0 リリースしました。

log python sphinx document

序

前回の記事からだいぶ間が空いてしまいました。どぅも、Python界の次期おっさん予備軍です。アラ◯ーと呼ばれる身分も、あと半年と少しを残すのみとなりました。。。

sphinxjp.themes.dotted 0.1.0 リリース

えー、さて。こんなものをリリースしました。

sphinxjp.themes.dotted · PyPI

ご存知の方はご存知、Python製ドキュメンテーションツールSphinxのHTMLテーマセットです。これは私が制作したモノとしては２つ目になります。

今回は、自分なりのコンセプトを持って制作にあたりました。

  • 基本のコンセプトは「ドットノート」
  • ビジネス臭くない
  • 自分なりに新しい要素を入れる

順番に説明をしようと思います。

一つ目。基本コンセプトですが、上にも書いたように「ノート」をイメージしてます。モノトーンの構成したのはそのイメージが下地にあったからです。なので、ヘッダやフッタ部分の色使いも、白い紙が自然に見せる陰影に近い色を選んでみました。元々はもう少し凝った感じで背景に罫線を入れてみる案も考えたのですが、自分の頭の中であまり上手いイメージが描けなかったので、結局採用はしませんでした。

二つ目。前作 sphinjp.themes.bizstyle はその名にある通り、職場やビジネスの場面で利用されることを想定し直線的なデザインにしたののですが、今回はそれとは真逆に振ってみたくなったので角丸のスタイルを採用してみました。ただし私個人はあまりコロコロとし過ぎたものも苦手なので角丸のサイズはだいぶ控え目にしてあります。また、画像を使わずCSSのみで調整しているため一部ブラウザ（IE、Opera等）では角丸で表示できないものがあります。予めご承知置きください。

三つ目。今回、自分としては初めての試みとしてjQueryを使ったエフェクトを突っ込んであります。と言っても大した事はしていなくて、グローバルTOCの表示を、SlideDown/Upで切り替えるだけです。しかもSlideDownの時のactionが微妙にスムーズじゃなくて、イケてません。jQueryを利用したデザインは今後も継続して取り組んで行きたい課題なので、ノウハウをお持ちの方からのツッコミ・アドバイスは随時歓迎です。

この他、今回からパッケージのソースはBitbucketではなく、Githubの方にしました。別にGithubに乗り換えたというのではなく、個人的にGitを使う機会を増やす目的でやったことなのですが、後になってBitbucketがGitもホスティング出来るようになったので「あれまー」というのが本心だったりします。


実際の見た目や使用感について、まずは上のURLリンク先の「Package Documentation」をご覧ください。このテーマを使って生成したパッケージのドキュメントを公開しています。興味・関心をお持ちの方は、是非お試し頂き、ご意見・ご感想・バグレポート等頂ければ幸いです。

結

今年も残すところあと２ヶ月半、というところまで来ました。出来ることならもう一つくらいHTMLテーマを作って締めくくるようにしたいと思います。

その時はまた、ここで告知しようと思います。期待せずにお待ちください。

sphinxjp.themes.bizstyle 0.1.3 リリースしました。

log python sphinx document

序

ども、Python界の風邪っぴきです。
暑かった夏もそろそろ収束モードでしょうか。日陰に入ると風がカラリとして気持ちよい日が増えましたね。

sphinxjp.themes.bizstyle 0.1.3 リリース

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


先日（ちょうど１ヶ月前）0.1.2 をリリースしたばかりだったんですが、一部のスタイルがあまりよろしくない感じだったのでちょっと直してみました。

具体的には Admonition というカテゴリ(?)に含まれるディレクティブに適用するスタイルです。

Sphinx で文書を書くときにいろいろと便利な機能を提供してくれているのがこのディレクティブですが、Admonitionはそのなかでも結構使われる場面が多いと思われます。と言ってもピンと来ないと思うのですが、次のような名前のディレクティブを使ってはいないでしょうか？

.. note::
   この関数はspamの電子メールを送付するには適しません。

.. warning::
   バージョン2.4.x ではサポートされていません。


これらは文書中に注釈やポイント等、読者に対しての注意を促すために用いられる告知ブロックを構成するためのディレクティブですが、Admonitionというのはそのディレクティブの総称に当たります。今回スタイルを定義したのはreStructuredText が公式に実装している以下のディレクティブです。

  • danger
  • error
  • warning
  • caution
  • attention
  • note
  • important
  • hint
  • tip
  • admonition


以下は今回適用したスタイルの表示サンプルです。


Sample — Sphinx theme for Business style documentation


この他、Sphinx で独自に拡張している versionadded, versionchanged, seealso もこのグループに含まれるようですが、今回は特に対応していないので sphinxjp.themes.bizstyle を使うと他とのバランスが悪い状態になってしまうかも知れません。

結

もし表示や色使い等で気になる点や修正の依頼などがあれば、リポジトリを置いている bitbucket.org の issues に意見を頂けると幸いです。

拝