ドキュメントの整備

[k2kobayashi]

コードに徐々にドキュメント用？のコメントを記載していっている．ドキュメント作成について何か経験的な知見があれば（例えばフレームワークの良し悪しや記載方法）教えてください．

[r9y9]

sphinxが使いやすいと思います。僕は https://github.com/librosa/librosa をよく参考にしています。ドキュメントのホスティングには、

• https://readthedocs.org/
• https://pages.github.com/

の２つは使ったことがあります。前者は、何より楽なのが良いです。githubのタグイベントをホックして、自動でバージョンごとのドキュメントのビルド、URLの切り替え（latest/stable）をやってくれます。デメリットとしては、例えばlibrosaのドキュメントにあるように (例. http://librosa.github.io/librosa/generated/librosa.core.stft.html#librosa.core.stft )、コードコメント中にpyplot.plot などを挟んで、ドキュメントに画像をはさみたい場合に、readthedocsのドキュメントビルド環境には画像を表示するバックエンドがないので、sphinxでドキュメントのビルド時に画像を生成できない、といったことがあります（sphinxでは、コードコメントにplot(x) 的なコードを書いて、ドキュメントビルド時に画像を生成して挿入する、といったことができます）。後者は、自由度が何よりのメリットでしょうか。自分でビルドしてプッシュすればよいので、何でもできます。ただし、その分手間は増える、といった感じです。

[k2kobayashi]

librosaのドキュメントとてもいい感じだね．Themeも選べる様なので，読みやすいやつを探すと良さそう．librosaのドキュメントのドメインが，librosa.github.ioになってるのは，pages.github.comをホスティングとして利用しているからなのかな？
librosaは，古参サービスっぽいけど，よくまとまってる様にみえるので積極的に真似していきたいね．

[r9y9]

ibrosaのドキュメントのドメインが，librosa.github.ioになってるのは，pages.github.comをホスティングとして利用しているからなのかな？

そうです。

librosaは何年も前から使ってますが、とても良くテストされていて、ドキュメントも豊富で、レビューもきっちりやっていて、ソフトウェアの開発、運用の参考になると思います。 librosaに初めてPRを出した時、あまりのレビューの丁寧さに感動した覚えがあります。

[k2kobayashi]

コメントを比較的追加したcleanブランチでmakeして生成されたdocsを下記のブランチにpushしましたhttps://github.com/TakedaLab/sprocket/tree/docs． themeは， デフォルトが読みにくい感じで，https://github.com/guzzle/guzzle_sphinx_theme が見やすそうだったのでGuzzleに変更しました．

[k2kobayashi]

毎回，適当なところからコピーして使いまわしているので雛形を作っておきたいと思います．オススメの雛形があればレコメンドください．
コメントテンプレート for function

'''処理の説明.

Parameters
----------

arguments1 : np.ndarray [shape=(`T`,)] 
    説明

arguments2 : scalar, int > 0
    max of row of `arguments1`

Returns
-------

return1 : np.ndarray [shape=(`T`, `dim`)]
    コードで利用されている変数は，``で囲む．

See Also
--------
sprocket.hogehoge

Examples
--------
例の部分は，>>> でコードを記載する．
>>> sprocket.print('hogehoge')
hogehoge
'''

[r9y9]

郷に入っては郷に従えということで、僕は https://github.com/numpy/numpy/blob/master/doc/HOWTO_DOCUMENT.rst.txt に習っています。Parameters, Returns, See Also, Examples などは、すべてnumpydocに従うものです。他はあまり知らないですが、chainerは異なるフォーマットを利用しているみたいです

[k2kobayashi]

Thanks. 一通り目を通してみます．