はじめに
こんにちは、Python界の情弱です。Goのコードリーディングをするにあたって、メモをSphinxで書こうと思ったんですが、Go用のドメインが見つからなかったので、標準で入っているCドメインとPythonドメイン、あと@shibukawa作のErlangドメインを参考にして作ってみました。
Sphinx本体でも各言語のドメインを取り入れていくというので、sphinx-contribではなく、直接本体にpull requestしてみようと思います。*1
作ったもの
Gitレポジトリはいまはbitbucketにあります。
ディレクティブ
いま対応しているディレクティブは次の通り
.. go:package:: package_name .. go:function:: func Function(arg type, ...) (return_type...) .. go:function:: func (typearg Type) Method(arg type, ...) (return_type) .. go:type:: struct/interface .. go:variable:: variable_name .. go:const:: constant_name
リンクを張るときは次のとおり
:go:pkg:`package_name` :go:func:`Function` :go:func:`(typearg Type) Method` :go:type:`struct/interface` :go:data:`variable_name/constant_name`
作ったきっかけ
Goは最近出来た言語なので、他の言語にもれず、コメントからドキュメントを生成するgodocという仕組みがあります。
しかしながら、これはPythonにおけるpydocと同じで、細かなドキュメントを書くにはしんどいです。幸いSphinxがソースコードハイライトにPygmentsを使っていて、それがGoにも対応しているので、あとはドメインさえあればドキュメント記述は問題なく出来るということと、Go言語のドメインが見当たらなかったので作ってみました。
作る上で参考になったもの
今回は作成にあたり @shibukawa に色々とアドバイスを戴いたのですが、僕が色々と作っていたら @shibukawa のドメイン作成熱に火がついたようで、次のようなドキュメントをsphinx-users.jpに公開してくれました。
あとは、その言語の特徴に併せて、今存在してるドメインのソースを見てちょこちょこと変えていったら出来ました。GoのドメインはCとPythonとErlangを参考にしました。
- birkenfeld / sphinx / source / sphinx / domains / — Bitbucket
- sphinx/sphinx/domains の中にC, C++, Python, JavaScriptなどがあります。
- birkenfeld / sphinx-contrib / source / — Bitbucket
- erlangdomain, rubydomain, phpdomain, javadomain などがあります。
今後の修正点
パッケージ名表記周り
Go自体はパッケージを読み込む際には階層構造はなくフラットになるんですが、ただ読み込む際に名前がぶつかる可能性はあります。たとえば、標準パッケージだと rand は crypto と math の両方にあるので、ドキュメントを記述する際には
.. go:package:: crypto/rand .. go:package:: math/rand
と区別してあげなければいけません。今のところ特にpackageの表記に関して制限はないので、普通に書こうと思えばリンクを
:go:func:`math/rand.FuncOne`
のように書けばいいんですが、さすがに冗長なので、なにかいい方法ないかなと考えています。
インデックス周り
いまはメソッドであることを表現するために
:go:func:`(Type) Method`
の形で名前を引いています。しかし名前の登録が括弧から始まってしまっているため、Indexをみた時にすべてのメソッドのインデックスがSymbolsとなってしまいます。これをTypeの頭文字で登録するようにしなければいけません。
