今回は Sphinx について触れてみます。
前回記事でweb2pyの補足ドキュメン作成について紹介しました（ web2py 補足ドキュメント ）。
このドキュメント作成に活躍しているのが、Sphinx だ。Python製のこのツールは、マニュアルのような文書を作成するのが得意だ。私も初めて利用してみた。スペースやインデント・改行が大きな意味を持っており文書内で使うマークも独特で、最初は取っ付きにくい。しかし慣れるに従ってサクサクと文書ができ上がっていく。
このSphinxのドキュメントにソーシャルボタンを追加しました。以下、設定方法をメモ書きします。
ソーシャルボタンの用意
まずソーシャルボタンを用意する。次のサイトを参考に各サイトにアクセスし、ボタンのソースを集める。
参考： Facebook・Twitterなどソーシャルボタン設置方法まとめ
今回は次のボタンを設置する
この内 Facebook が一番分かりにくかった。ページの言語設定を判断して表示言語を切り替えると参考サイトにも書いてあったが、結局上手く判定してくれないのでソースの言語コード箇所を ja_JP に変更した。この他参考サイトには OGP の説明もあったが、今回は特に設定しなかった。Sphinxに対する設定
次の手順でSphinxの設定を行う。
- Sphinxのプロジェクトフォルダ下にある _templatesフォルダに layout.html という名前のファイルを作成する。
- layout.htmlを編集し、ソーシャルボタンのソースコードを追加する。
- make html コマンドでSphinxドキュメントを生成する。
layout.htmlファイルの記述方法だが、ソーシャルボタンの設置位置によって記述が変わる。今回はコンテンツ本体の上部に設置する。このため、documentブロックに次のように記述する。
{% extends "!layout.html" %}
{% block document %}
{{ super() }}
{% endblock %}
- {% extends "!layout.html" %} は既存のlayout.htmlを拡張するという意味。ファイルの先頭に記述する必要がある。
- {% block document %} は documentブロックの意味。このブロックは {% endblock %} の記述で終わる。
- {{ super() }} は継承した documentブロックの中身。これを書かないとコンテンツは表示されない。 super() の上にソーシャルボタン記述するため、コンテンツの上部に表示される。下部だったら super() の下に記述する。
この他 「Google+1」 ではコードが２つに別れており、一方は headerタグ内もしくは body終了タグ直前に貼り付ける、と書かれている。このため次のように記述する。
{% block extrahead %}
{% endblock %}
- {% block extrahead %} は headerタグに情報を追加設定する。
最終的に全部合わせると、次のようになる。 （コメントの箇所に実際のコードを挿入する）
{% extends "!layout.html" %}
{% block extrahead %}
{% endblock %}
{% block document %}
{{ super() }}
{% endblock %}
ソーシャルボタンのコードを Table タグで囲んでいるが、これは何も設定しないと 「Facebookいいねボタン」 だけ改行して表示してしまうからである。
実際の表示は次のようになる。
個別ページごとにソーシャルボタンを設定
ソーシャルボタンをSphinxドキュメントに表示することは成功したが、設定はまだ終わらない。なぜなら 「はてなブックマーク」 と 「Facebookいいねボタン」 を押すと、ドキュメント全体がブックマークされてしまうからである。これについては次のように変更すればよい。
「はてなブックマーク」 と 「Facebookいいねボタン」 のソースを見ると次の箇所がある。
href="http://b.hatena.ne.jp/entry/http://hiho.bitbucket.org/" data-hatena-bookmark-title="hiho's docs"
data-href="http://hiho.bitbucket.org/"この部分を個別記事毎に変更するようにする。
Sphinx のテンプレート言語は jinja だが、幾つかの変数を持っている。今回使えそうな変数は次の３つだ。
| pagename | 現在のファイルの “ページ名” です。reSTのソースから生成されていたらドキュメント名になります。あるいは出力ディレクトリからの相対パス名から拡張子を抜いた名前 ([ディレクトリ/]拡張子なしのファイル名) となる、階層名付きの名前になります。 |
| file_suffix | ビルダーの out_suffix アトリビュートの値です。出力ファイル名に付く拡張子などです。標準のHTMLビルダーの場合には、通常は .html になります。 |
| title | 現在のドキュメントのタイトルです。これは <title> タグで使用されます。 |
それではテンプレート言語の変数を利用して、先ほどのソースの箇所を修正してみる。
href="http://b.hatena.ne.jp/entry/http://hiho.bitbucket.org/{{ pagename }}{{ file_suffix }}"
data-hatena-bookmark-title="hiho's docs {{ title }}"
data-href="http://hiho.bitbucket.org/{{ pagename }}{{ file_suffix }}"
修正したソースを保存して試してみる、・・・ 個別ページでちゃんとブックマークされるようになった。
参考
Sphinx-Users.jp - Google AnalyticsやGoogle Adsenceを貼りたい
Sphinx - テンプレート
facebook Guide - 「いいね！」ボタンを設置しよう
「Facebookいいねボタン」 で私が生成したボタンのソースは、インターネット上の説明サイトでよく使われている iframeのソースと違うようです。もし違うタイプソースをお持ちの時は、変更が必要な箇所に上で説明した変数を挿入してください。
他に注意点としては 「google+1ボタン」 なのですが、初めて使ってみようとしてプロファイル停止状態になってしまいました。後でテストして動かなかったら記事を修正します。→「google+1ボタン」も正常に動くようです。
追記 2012/02/01
Twitter と Google+1 はURLを指定しなくても個別ページをマークしてくれます。しかしトップページに関しては、その限りではありません。次のようなURLがあるとします。
これらのURLが示すページが同一だった場合に、URLを指定していない Twitter/Google+1 は違うページとして認識してしまいます。このため Twitter/Google+1 についてもURLを指定した方が良いです。
data-url="http://example.com/{{ pagename }}{{ file_suffix }}"
href="http://example.com/{{ pagename }}{{ file_suffix }}"