2017年11月16日

ブロードバンドタワー國武です。

みなさん、運用ドキュメント書いてますか?もういうまでもなく、書くこと自体が楽しくなっちゃう Sphinx をお使いの人が多いと思うんですが、今回はその Sphinxでの独自ディレクティブの定義についてです。

いやいや Sphinx とか知らんし……という方は、是非 Sphinx-users.jp の方々が書かれた

をご一読ください。きっと使いたくなるはず!

さて、そもそもこの記事を書こうと思ったのは、 Pythonの勉強がてら、Ansible の playbook から Sphinx のドキュメントを吐き出すツールをお家で書き始めたのがきっかけです。

Sphinxで独自ディレクティブを定義

さて、お家で件のツールを書いていたところ、ansible の変数一覧を索引に載せたくなりました。そのための方法を調べたところ、独自ディレクティブを定義することでその用が満たせそうだったので、実際に試してみた記録が下記になります。

どうなるのか?

こんな感じで表示できます。

索引例

独自ディレクティブ(ansibleval)定義の実際

独自ディレクティブとして ansiblevalを定義するには、conf.py に追記します。

def setup(app):
    app.add_object_type('ansibleval', 'ansibleval',
                        objname='ansible configuration value',
                        indextemplate=u'pair: %s; Ansible設定値')

すると、ドキュメント中に

.. ansibleval:: consul_domain

  consulで提供される内部向けDNSサーバで利用される suffix domain 名。

と書いておけば、上に挙げたような索引が作成されます。

おわりに

さて、今回は Sphinx 知らない人を全力で置いてきぼりにする小ネタを書いてみましたが如何でしたでしょうか。少しでも Sphinx に興味を持たれた方は、是非使ってみてください!

本ブログの情報につきましては、自社の検証に基づいた結果からの情報提供であり、
品質保証を目的としたものではございません。

投稿者: Koichi KUNITAKE

XenServerやLinux周りを触ってます。IPv6はボチボチ……