use No::Name;

■[sphinx][log] Sphinx Advent Calendar 16日目

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_top>
  + 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 さんです。よろしくお願いします。

参考

• HTML theming support — Sphinx 1.1.3 documentation
• HTML テーマ事始め - 上級者編

ツイートする

Permalink | コメント(0) | トラックバック(0) | 12:55

■[python] PySpa アドベントカレンダー 2日目

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

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

そもそもの話

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

そのときの会場は、いま自分が在籍している会社の会議室でした。

Sphinx翻訳ハッカソン(2010/09/05) :: ドキュメンテーションツール スフィンクス Sphinx-users.jp

当時の自分は某巨大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 さんです。よろしくお願いします！

ツイートする

Permalink | コメント(0) | トラックバック(0) | 02:28

■[log][python][sphinx][document]sphinxjp.themes.bizstyle 0.1.5 リリースしました。

序

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

sphinxjp.themes.bizstyle 0.1.5 リリース

sphinxjp.themes.bizstyle 0.1.5 : Python Package Index

しばらくもやもやと考えていたことを実行に移してみた、という意味でのアップデートは一つ前のリリース（0.1.4）でやっていたので、そこからの大きな変更はありません。

今回のリリースの目的は頂いた pull request をHEADにマージする、という意味合いが大きいです。

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

結

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

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

ツイートする

Permalink | コメント(2) | トラックバック(0) | 00:17

■[log][sphinx][python][document]sphinxjp.themes.impressjs 0.1.2 リリースしました。

序

前回の更新からだいぶ間が空いてしまいました。Python界の根無し草です。

厳しめの寒さが少しずつ緩み始めた昨今ですが、いかがお過ごしでしょうか?

sphinxjp.themes.impressjs 0.1.2 リリース

sphinxjp.themes.impressjs 0.1.2 : Python Package Index

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

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

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

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

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

結

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

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

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

ツイートする

Permalink | コメント(0) | トラックバック(0) | 03:25

■[log][python][sphinx][document]sphinxjp.themes.dotted 0.1.1 リリースしました。

序

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

sphinxjp.themes.dotted 0.1.1 リリース

sphinxjp.themes.dotted 0.1.1 : Python Package Index

さて。タイトルの通りなんですが、先日リリースした 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の方も「条件分岐を使って不要な定義を書き出さない」という記述ができるので、動的にスタイルの定義を切り替える事も出来ますしなかなかどうして便利です。

結

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

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

ツイートする

Permalink | コメント(0) | トラックバック(0) | 17:41