Sphinxドキュメントを本番と開発で外部リンク先を変える

Sphinxドキュメントから外部のURLにリンクをする時、複数箇所同じURLベースだったら extlinks 拡張を使うと便利。

conf.py

extensions += ['sphinx.ext.extlinks']
extlinks = {'docbase': ('http://hoge.jp/docs/%s', '')}

hoge.rst

:docbase:`hogeへ <hoge/fuga.html>`

これで、 http://hoge.jp/docs/hoge/fuga.html にリンクが貼られる。

ただ、conf.pyのextlinksにセットしたベースのURLって、本番と開発みたいな環境で切り替えたい時がある。
自分のPython力が足りなくて、苦肉の策っぽいんだけど、一応実現できている。

conf.py

extensions += ['sphinx.ext.extlinks']

if os.getenv('BUILD_ENV', 'development') == "production":
  extlinks = {'docbase': ('http://production.jp/docs/%s', '')}
else:
  extlinks = {'docbase': ('http://hoge.jp/docs/%s', '')}

productionと、それ以外という手抜きな分岐だけど、この状態で

% BUILD_ENV=production make html

とすれば、production.jpへのリンクになって便利。

2016/6/9 追記
もっとSphinxらしい記述の仕方もあった。

conf.py

extensions += ['sphinx.ext.extlinks']

if "production" in tags: # ここが違う
  extlinks = {'docbase': ('http://production.jp/docs/%s', '')}
else:
  extlinks = {'docbase': ('http://hoge.jp/docs/%s', '')}

これで、

% make SPHINXOPTS='-t production' html

としても、同じ結果が得られる。

参考

ドキュメントを部分的に公開/非公開にしてビルドする - Python製ドキュメンテーションビルダー、Sphinxの日本ユーザ会