読者です 読者をやめる 読者になる 読者になる

Sphinxドキュメントにソーシャルボタンを設置して、bitbucketに公開してみた

bitbucket Sphinx

結果はこれ → http://toruuetani.bitbucket.org
リポジトリはこれ → https://bitbucket.org/toruuetani/toruuetani.bitbucket.org

ソーシャルボタンの設置

参考URL

基本的には参考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%
)