« ETロボコン参加チームの方は astah* professionalを使えます | トップページ | 6/4(土)のUPGRADE JAPANは盛況でした »

Sphinx、ビルド設定ファイルでHTML出力の見た目を変える

私が Sphinxを使っているのは、テキストファイルを書いて、コマンドプロンプトで make html を実行すれば簡単にHTMLファイルを生成できるからです。例えばウェブサイトを更新したい時に、変更箇所がほんの少しなら HTMLのタグを直接書くこともあります。しかし、Sphinxのように、タグやCSSを意識せずにテキストエディタで文章を書いていけば良いというのはとても楽ですし、書きたい文章以外のことを考えなくてすみます。使いこなすと CSSも設定できますが、知らなくても予め用意されたテーマを使うことで見た目の整ったドキュメントを作成できます。

今日は、ビルド設定ファイルと呼ばれる conf.py でオプションを設定することで、生成されるHTMLファイルの見た目を少し変えてみました。詳しいオプションの解説は "Sphinx 1.1 Documentation" HTML出力のオプションをご覧ください。

[注] この記事ではWindows環境で使っているため、「フォルダ」という語を使いますが、他の環境を使用している方は「ディレクトリ」と表現されることもあります。

conf.py は、Sphinxのプロジェクト名で作成したフォルダの中に出来る sourceフォルダに入っています。.rst ファイルと同じようにテキストエディタで開いて編集できます。開いてみるとシャープ記号(#)で始まる行がほとんどで、じっと見るとちらほらと表示に関係しそうな文字が混じっています。

最初に何やら説明のような文章があり、"General configuration"の部分を過ぎると "Options for HTML output"が見つかります。ここからがHTML出力のオプションですが、シャープ記号(#)で始まっている行は、ビルド(make htmlを実行すること)では無視されます。設定したいオプションは、必ず行頭のシャープ記号を削除して、イコール記号(=)の後ろにその内容を入力してください。

まず、初期段階でHTMLを生成した際の表示です。
201106011_2

テーマを設定してみました。ShinxではHTMLのテンプレートファイルが「テーマ」として予め用意されています。その中から「haiku」を選びました。

html_theme = 'haiku'

結果はこちら。見た目がガラっと変わりましたね。
201106012

次に、haikuテーマでページの一番上に表示されるタイトル(上の画像で「support-service v0.1 documentation」となっているところ)を変更し、ロゴ画像を入れてみます。

html_title = 'Product Support Guide'
html_logo = 'ロゴ画像のファイル名をパスで指定'

結果はこうなりました。
201106013

最後に、また別のテーマ「traditional」での表示を見てから終わりにします。
201106014

|

« ETロボコン参加チームの方は astah* professionalを使えます | トップページ | 6/4(土)のUPGRADE JAPANは盛況でした »

Sphinx」カテゴリの記事

コメント

コメントを書く



(ウェブ上には掲載しません)


コメントは記事投稿者が公開するまで表示されません。



トラックバック

この記事のトラックバックURL:
http://app.f.cocolog-nifty.com/t/trackback/98967/40221447

この記事へのトラックバック一覧です: Sphinx、ビルド設定ファイルでHTML出力の見た目を変える:

« ETロボコン参加チームの方は astah* professionalを使えます | トップページ | 6/4(土)のUPGRADE JAPANは盛況でした »