Sphinxドキュメントにソーシャルボタンを設置して、bitbucketに公開してみた
結果はこれ → http://toruuetani.bitbucket.org
リポジトリはこれ → https://bitbucket.org/toruuetani/toruuetani.bitbucket.org
ソーシャルボタンの設置
参考URL
- 今日のPython: Sphinx にソーシャルボタンを設置する
- はてなブックマークボタンの作成・設置について
- Twitter / ツイートボタン
- プラスワン ボタン
- Like Button - Facebook開発者
基本的には参考URLの通りにやれば問題ない。ただし、このままだと確認用にビルドしたドキュメントでもソーシャルボタンが設置され、表示に失敗する。それだけならまだいいが、ドキュメント上部に表示すると失敗するまで本来のドキュメントまで表示されない。なので確認用ビルド時と公開用ビルド時にソーシャルボタンの設置・非設置を切り替えられるようにしてみた。
まずはSphinxドキュメントが $/source にある場合、 $/source/_templates/layout.html を下記の内容で追加する。
はてなとfacebookについては、「http://toruuetani.bitbucket.org/」の部分を公開URLにあわせて修正すること。
{% extends "!layout.html" %}
{%- block document %}
<div class="documentwrapper">
{%- if render_sidebar %}
<div class="bodywrapper">
{%- endif %}
<div class="body">
{% if need_social_buttons %}
<div style="height: 30px;">
<table cellpadding="5px">
<tbody>
<tr><td>
<!-- hatenaコード -->
<a href="http://b.hatena.ne.jp/entry/http://toruuetani.bitbucket.org/{{ pagename }}{{ file_suffix }}"
class="hatena-bookmark-button"
data-hatena-bookmark-title="{{ title }}"
data-hatena-bookmark-layout="standard"
title="このエントリーをはてなブックマークに追加">
<img src="http://b.st-hatena.com/images/entry-button/button-only.gif" alt="このエントリーをはてなブックマークに追加" width="20" height="20" style="border: none;" />
</a><script type="text/javascript" src="http://b.st-hatena.com/js/bookmark_button.js" charset="utf-8" async="async"></script>
</td><td>
<!-- Twitterコード -->
<a href="https://twitter.com/share"
class="twitter-share-button"
data-count="horizontal">Tweet</a>
<script type="text/javascript" src="//platform.twitter.com/widgets.js"></script>
</td><td>
<!-- google+1 headerタグ用コード -->
<script type="text/javascript" src="https://apis.google.com/js/plusone.js">
{lang: 'ja'}
</script>
<!-- google+1ボタン表示用コード -->
<g:plusone></g:plusone>
</td><td>
<!-- facebookコード -->
<div id="fb-root"></div>
<script>(function(d, s, id) {
var js, fjs = d.getElementsByTagName(s)[0];
if (d.getElementById(id)) {return;}
js = d.createElement(s); js.id = id;
js.src = "//connect.facebook.net/ja_JP/all.js#xfbml=1";
fjs.parentNode.insertBefore(js, fjs);
}(document, 'script', 'facebook-jssdk'));</script>
<div class="fb-like"
data-href="http://b.hatena.ne.jp/entry/http://toruuetani.bitbucket.org/{{ pagename }}{{ file_suffix }}"
data-send="false"
data-layout="button_count"
data-width="450"
data-show-faces="true"></div>
</td></tr></tbody></table>
</div>
{% endif %}
{% block body %} {% endblock %}
</div>
{%- if render_sidebar %}
</div>
{%- endif %}
</div>
{%- endblock %}
本来なら body ブロックだけ用意すればいけるかと思ったが、ドキュメント側で body ブロックを完全にオーバーライドしてしまうらしい。なので Sphinx のデフォルトテンプレートから layout.html をコピーしてきて、ソーシャルボタン設置コードを追記した。さらにそのコードを if ブロックで切り替えられるようにして、その切り替えは、make.batにオプションを追記することで可能にした。
ポイントは %SPHINXBUILD% (sphinx-build) に渡すパラメータ「-A need_social_buttons=1」。「-A name=value」の形式で渡すと、Sphinxテンプレート内の変数をオーバーライドできる。boolean型の場合は0または1を渡せばいい。
REM ソーシャルボタン有効化オプション if "%1" == "html-publish" ( %SPHINXBUILD% -b html -A need_social_buttons=1 %ALLSPHINXOPTS% %BUILDDIR%/html if errorlevel 1 exit /b 1 echo. echo.Build finished. The HTML pages are in %BUILDDIR%/html. goto end )
こうすると、いつものように
make.bat html
するとソーシャルボタンを設置しないHTMLが生成されて、
make.bat html-publish
するとソーシャルボタンを設置するHTMLが生成される。
Sphinxドキュメントの公開
参考URL
次は作成したHTMLの公開。せっかく bitbucket のアカウントを持ってるので、 Sphinx ドキュメントの公開先に使ってみた。ほぼ参考URLの通りで、作成したHTMLもリポジトリに登録するのが注意点。
作成するリポジトリ名は、bitbucketのアカウント名.bitbucket.org とする。あとは通常のリポジトリと同じように使えばいい。
Sphinxでドキュメントをビルドすると、指定したビルドディレクトリ配下にターゲットに応じたディレクトリが作られて、その下に生成したドキュメントが配置される。HTMLを指定した場合は
ビルドディレクトリ/html/index.html
といった感じ。これを毎回リポジトリのルートディレクトリまでコピーするのも面倒なので、ビルドしたらルートディレクトリにHTMLをコピーするバッチファイルを用意した。DOC_DIRを各環境にあわせて変更すればそのまま使えるはず。あとは生成したHTMLをコミットして、bitbucketにpushすれば公開される。
@ECHO OFF SET ROOT_DIR=%~DP0 SET DOC_DIR=%ROOT_DIR%\doc CD /d %ROOT_DIR% PUSHD %DOC_DIR% IF "%1"=="publish" ( CALL make.bat html-publish ) ELSE ( CALL make.bat html ) POPD IF EXIST %DOC_DIR%\build\html\index.html ( XCOPY /S /Q /Y %DOC_DIR%\build\html\* %ROOT_DIR% )
