Subscribed unsubscribe Subscribe Subscribe

sphinxjp.themes.basicstrap 0.2.0 リリースしました

というわけで久しぶりのブログ更新。

あれですね2012年いつのまに終わってたんですかね。2012年12月に世界が終わるとかなんとか言ってた人たちは今どんな気持ちで生活してるんですかね。ちょっと話てみたいですね。

そんなわけでSphinxというドキュメンテーションツールのデザインテーマをこさえてみました。Twiter Bootstrapという、今や猫も杓子も使い始めるほどの人気のアレをベースにしてみたテーマです。(実際、猫も杓子も使えるわけではない)

制作に当たっては、面識はございませんが@shkumagaiさんや、@shimizukawaさんがPyPiにあげてるテーマが大分参考になりました。ありがとうございます。参考にしましたっていうか、setup.pyやらなんやらの書き方はもうほぼパクリ超インスパイアされました。

@shkumagaiさんのこの資料にも大変お世話になりますた。

BootstrapをベースにしたSphinxテーマは既に幾つかありますが、ヘッダーメニューに色々入ってたりして、個人的にはもうちょっとシンプルなのないかなー的に探していたのが事の発端です。

結局求めるものは見つからなかったので、Sphinxのdefaultテーマを単純にBootstrap対応しました的なもの作り始めた次第です。

今回は利用者の方が、オプションを変えるだけで、ある程度自分の気に入ったデザインにできるように頑張ってみました。デザインの変更の仕方については、イメージが付きやすいように簡単にまとめみましたのでこれを見ながらhtml_theme_optionsの設定をしてみてください。

デザインをいじいじする例

デフォルトでは凄く簡素な感じになっています。

f:id:tell-k:20130213002501p:plain

conf.pyのhtml_theme_option下記のように変えてみます。

html_theme_options = {
    'rightsidebar': True,     
    'sidebar_span': 4,
    'nav_fixed': True,
    'nav_width': '900px',
    'content_fixed': True,
    'content_width': '900px',
    'googlewebfont': True,
    'googlewebfont_url': 'http://fonts.googleapis.com/css?family=Text+Me+One',
    'googlewebfont_style': "font-family: 'Text Me One', sans-serif",
    'inner_theme': True,
    'inner_theme_name': 'bootswatch-united',
}

するとこんな風になります。

f:id:tell-k:20130213002759p:plain

あーサイドバーウゼーって人は、下記のように設定して1カラムにすることもできたりします。

html_theme_options = {
    'nosidebar': True,    
    'googlewebfont': True,
    'googlewebfont_url': 'http://fonts.googleapis.com/css?family=Jacques+Francois+Shadow',
    'googlewebfont_style': "font-family: 'Jacques Francois Shadow', sans-serif",
    'inner_theme': True,
    'inner_theme_name': 'bootswatch-amelia',
}

f:id:tell-k:20130213004239p:plain

是非お試しください。

以下なんか雑多メモ

  • カスタムテーマを作るための簡単なチュートリアル的なものを、どっかに纏めておきたい(備忘録的な意味で)
  • DOCTYPE宣言はHTML5したった。
  • カスタムロールの作り方は以下の記事が参考になった。
  • ディレクティブとロールは別ものだという事に気づいた。
  • FontAwesome用のアイコンタグは iタグを使いたかったけど、docutilsをチラ見する限り、任意のタグを吐き出すの面倒くさそうだったのでspanタグ我慢した。(簡単なやり方があるのかもしれんけど。)
  • apache 2.0 ライセンスのもの使って配布する時は、元のライセンスの場所を明記する必要がある。
  • sphinxjp.themes.coreをベースに作ったけど、sphinxjpのどこかに連絡した方がいいんだろうか(遅い)
  • theme.confのオプションはテンプレートでは theme_xxxxという変数で参照できる。
    • booleanの判定は (theme_googlewebfont|tobool) みたいな感じでtoboolをかますと良い。
  • 検索窓が無かったのはバグです
  • スマホ対応? それ https://readthedocs.org/ で出来るしww とか言わんといて。
  • スマホ用にもうちょっと最適化したい
  • Twitter Bootstrap 2.3.0 リリースされたのは見なかった事にした。Bootswatch, Font Awesomeの対応状況をみながら対応する。
  • 0.1.x はヘッダーカラーが黒になってるけど、0.2.0は白になってるので気をつけて。黒がお好みの方はheader_inverse_colorをTrueにしてくだしあ。
  • 実はちょいちょいデザインが崩れてるぽい所があるので、ちゃんと直さな。
  • Google Web Fontとかでデカいフォントを選ぶとけっこうくずれるケースがあるのを今みつけた。。
  • 多分最低限の事しか対応できてないので、なんかデザインが崩れるとかあったらご連絡ください。

以上おわり