sphinxでautodocを使用する場合はプライベートメンバー('_'から始まるメンバー)はデフォルトで非表示となっていて、docstringが出力されない。出力する場合には、autodoc-skip-memberというカスタムメソッドを使用して表示するメンバーを指定すれば良いらしいが、これだと手間が増える。

sphinxのソースに手を入れない場合の出力方法:

.. autofunction:: app.views._get

これを表示したいプライベートメンバーごとにrstファイルに書いてやると出力されるようになる。

...これはめんどくさい。

そもそも、何故プライベートメンバーが出力されないのか。理由は2つ。

  1. だってプライベートでしょ?表示するのおかしいじゃん。
  2. アンスコ2つ'__'から始まるメンバーも表示されるでしょ?これ必要?

1.の理由については、確かに外部から隠したい理由もあるし、勝手に使われると困るだけの理由もあるから、同意せざるを得ない。しかし、開発中となると話は別。内部向け関数はどうしても知っておく必要があるし、開発者向けのドキュメントは残しておく必要がある。よって、(自分にとっては)ドキュメントを出力しない理由にはならない。

2.の理由については、完全に同意。でも非表示にしたいのは'__'メンバーであって、'_'メンバーじゃない。自分の書き方がおかしいのかもしれないけど、マングリングしたいview関数は'_'にしているので、'__'とは別に考える必要がある。

で、autodocのソースを見てみると、該当箇所発見。

sphinx/ext/autodoc.py : L538
if want_all and membername.startswith('__'): #もともとはアンスコ1つ'_'
# ignore members whose name starts with _ by default
skip = True

こういうふうに'_' → '__'としてやれば、不要なメンバーは今まで通り非表示とすることができて、表示したいプライベートメンバーは表示させることができる。でもなんかなぁ。うまいやり方じゃない気がする。