この記事はMaya-Pythonアドベントカレンダー12月11日の記事です。

はじめに

Pythonの機能の一つにdocumentation stringsというものがあります。

モジュール・クラス・関数などに下記のように文字列を記述することでドキュメントとして解釈されます。

def sayhello():
    u"""こんにちわと元気に挨拶する。"""
    sys.stdout.write(u"こんにちわ！")

helpメソッドに渡すと整形して出力してくれるので、関数の使い方を調べるのに使用します。

>>> help(sayhello)
Help on function sayhello in module __main__:

sayhello()
    こんにちわと元気に挨拶する

標準モジュールも当然記述されています。

>>> import os
>>> help(os.path.abspath)
Help on function abspath in module ntpath:

abspath(path)
    Return the absolute version of a path.

検証環境

Windows10
Python 2.7.12
PyCharm 2016.3
Sphinx 1.5
Maya 2016 Extension2

弊社で抱えている問題

弊社では多数のモジュール・メソッド・クラスを共有ライブラリとして管理しています。現時点でも全てを記憶しておくことは不可能な数のファンクション数になっています。
このうちmayaパッケージはmaya組み込みPythonでしか動作しません。その他にも組み込みPython依存のパッケージもありますが、今回はmayaに限定して話を進めます。

stu/
  __init__.py
  maya/
    __init__.py
    skin.py
    他多数・・・
  path.py
  pyside.py
  他多数・・・

共有ライブラリの利用を促進する
車輪の再開発を避ける

上記2点の理由から、欲しい機能で簡単に検索出来て、メソッドの引数の仕様についても視認性の高いシステムが求められています。

テストコードも作成しているのでテストコードを見れば大体の使い方はわかるのですが、当然のことながらどのような経緯で現在の仕様になっているのかはわかりませんし、そもそもテストコードが不十分なことが多いです。

そこで「きちんとdocstringに注意書きとか残しておこうよ」という話になるのですが、私自身あまり積極的には書いていません。

人間が行動には動機が必要なのです。

ではどうやって動機付けしてやろうか。ということでdocstringを見つめ直してみたいと思います。

メンテナンスしない問題

PEP8でも触れられているように、コードとコメントが一致しないのは最悪です。どちらが正しいのか分かりません。メンテナンスしないコメントなど書かないほうがマシでしょう。

などという言い訳ばかりして書かないのは何故か？単純に自分に対して恩恵が無いからではないでしょうか。

Pythonは日々進化しています。
Python3.5からはType Hints（PEP484）という変数の型を定義する機能が追加されています。引数および返り値の型を定義しておくことが可能になり、エディタがサポートすれば返ってきた変数のメソッドを候補として表示することができます。
PyCharmではType Hinting機能として、Python3.5のType Hintsと、docstringsに記述する方法をサポートしているようです。

これはdocstringをメンテナンスする動機になりそうです。

では、以下の検証を行い、docstringを便利に使いながらHTMLのドキュメントを手に入れたいと思います。

PyCharmのType Hinting
SphinxでドキュメントをHTML化して検索

Type Hintingを検証

Type HintsはPython 3.5で導入されたそうなので、一部コメントでの表現方法はあるそうですが、Python2では使用できないので思い切って却下です。

まずは、いつものように、Project Interpreterがmayapyになっていることを確認。これを怠るとpymelの型などを定義しても機能しません。

関数の返り値を定義してみます。rtypeでSkinClusterを指定してみます。
で、試しに関数呼んで変数に格納します。

その変数からメソッドをタイプすると・・・SkinClusterオブジェクトのメソッドが候補に上がります。もちろん親クラスのメソッドも。素晴らしい・・・

これであっさりとrtypeを書かない理由がなくなりました。

Sphinxを検証

PythonにはソースコードからHTMLドキュメントを自動生成する仕組みはいくつかありますが、最近はPython以外のプログラム言語のサポートにも力が入っているSphinxが最も一般的と言えるでしょう。Python自体の公式ドキュメントもSphinxです。というかそのために開発されたそうです。

Sphinxでドキュメントの自動生成して、docstringに書いた情報を検索できるようにします。

とりあえずpipでsphinxをインストール。

"C:\Program Files\Autodesk\Maya2016\bin\mayapy.exe" -m pip install sphinx --user

PyCharmでもSphinxが使えるようになっているので、ドキュメントディレクトリを指定します。今回はC:\sample\sphinxとします。

Sphinx Quickstartを実行してインタラクティブに設定ファイルを作成します。基本的に言語をjaにしたくらいで後はデフォルトでOK。（説明が雑ですいません）

これだけだとdocstringsは無関係でreStructuredTextフォーマットのテキストファイル（.rst）からhtmlを作成するだけなので、sphinx-apidocという機能を別途使ってソースコードからAPIドキュメントを生成する.rstファイルを生成します。
コマンドラインでの実行になります。

%USERPROFILE%\AppData\Roaming\Python\Scripts\sphinx-apidoc.exe ライブラリのパス -o C:\sample\sphinx

これで準備完了。続いてドキュメント生成の実行です。
PyCharmに戻って、Run/Debug Configurationsから新規Configを作ります。Python docs/Sphinx taskというのがちゃんと用意されてますね・・・inputとoutputを指定して完了です。Interpreterはmayapyになっていると思いますが、Sphinxはドキュメント化するモジュールをインポートしてdocstringsを取得するので、通常のPythonではインポートエラーが起こるためドキュメント化も失敗しますのでご注意ください。

で、いつものようにRun。C:\sample\sphinx\_build\index.html（その他多数）が生成されるはずです。

index.htmlを開きます。デフォルト状態だとそっけないhtmlが生成されますが、とりあえず検索してみましょう。

お、結果出た。（１つはゴミです）

おおお！きちんとdocstringに記述した返り値の型が記述されています。

まとめ

docstringsは多くのノウハウがウェブから得られました。マークアップのフォーマットはいくつか候補があるようですが、とりあえずはPython標準マークアップであるreStructuredTextで書いておくことにします。
Qiitaで書いているこの文章もそうですが、世間的にはマークアップ言語はmarkdownが事実上の標準かな？・・・と思わなくもないので少し不安もありますが、そもそもそんなに複雑な構成のドキュメントが目的ではないので結論を急ぐ必要はありません。またの機会に考えてみることにします。

Sphinxはコマンドラインで実行するにはちょっと敷居が高いと感じますが、PyCharm上で実行することで面倒な部分はほとんど隠ぺいしてくれます。
実はものすごく試行錯誤を繰り返したので、結果PyCharmを使えばアッサリした手順になってしまうのが少し悔しい。

結局またもやPyCharm最高という結果になってしまった。

参考

PyCharm での type hinting を使いこなす
 PyCharm (IntelliJ) で Sphinx で楽にドキュメントを書く

ドキュメンテーション文字列 再考