本稿は Qiita 投稿記事 のバックアップです．

概要

Sphinx テンプレートの一つ sphinx_rtd_theme では， メタデータ :github_url: に URL を渡すことで，Edit on GitHub のリンクを生成してくれる．

ではそのメタデータはどこで定義するのか？という話．

メタデータの定義

Sphinx におけるメタデータは二種類ある．一つは今回必要なテンプレートの処理に使うメタデータであり， もう一つは HTML の meta タグを出力するためのものである．

前者は，.rst ファイルの先頭付近（A field list near the top of a file）に置く必要がある． 曖昧な表現だが，要するに他のマークアップより前に書いておけば良い．

:github_url: https://github.com/jkawamoto/roadie-gcp

.. ここから本文を始める

などとすれば良い．

ちなみに，後者の方は .. meta:: で始まるセクションに記述する．

.. meta::
  :viewport: width=device-width

メタデータの一括登録

上記の通り，各 .rst ファイルの先頭に :github_url:メタデータを追加すれば， 生成されたドキュメントには GitHub へのリンクが付く． しかし，一々記述するのは手間なので，rst_prolog オプションを使って一括登録する．

conf.py に rst_prolog 変数を定義すると，その内容を各 .rst ファイルの先頭に追加してくれる． よって，

rst_prolog = """
:github_url: https://github.com/jkawamoto/roadie-gcp

"""

を conf.py に追加すれば，生成されたドキュメントの全ページに GitHub へのリンクが付く．

ちなみに生成されたドキュメントは http://jkawamoto.github.io/roadie-gcp/ のようになる．