ドキュメント移行に関する議論など

[tkf]

#16 に関する議論ですが、 twitter でやるより日本語でも良いから issue にでやったほうが便利じゃないかと思ったのでこっちに作ってみましたがどうでしょう？ twitter のほうが良いですか？

放っておくとマージが辛くなりそうなので、決めたほうが良いと思うこと (後の方に書いてますが、 sphinxcontrib-emacs の現状にかなり左右されると思います)：

1. Document deferred using sphinxcontrib-emacs #16 のマージを sphinxcontrib-emacs のリリースまで待つかどうか。
2. もしリリースまで待つなら、 docstring の移行を Document deferred using sphinxcontrib-emacs #16 でやるかどうか。 docstring 以外の移行を Document deferred using sphinxcontrib-emacs #16 でしてしまって、さっさとマージするのもありだと思います。 API のページ (autodoc 経由で作られたページ) は「実験的に公開してるのでフォーマット崩れても気にしないでね」みたいな態度もありかもしれません。
3. もしリリースまで待た ない で docstring の移行を Document deferred using sphinxcontrib-emacs #16 でやるなら、 docstring のテンプレートをどうするか。 ReST にどれくらい依存するか? 依存するにしても色々書き方あるけれどどうするか?

sphinxcontrib-emacs の現状なんですが、
ttps://github.com/flycheck/sphinxcontrib-emacs/issues/12 (←2chっぽい)
で議論した感じだと、「ReST マークアップに *Help* を組み合わせる案、良いと思ったんだけど色々問題出てきてやっぱやめようか迷ってる。ReSTの処理系を色々弄って実験してる最中だし忙しいし、リリースまだまだ遠いかも。」みたいな感じらしいです。

ad147a3 や 1814a40 で提案した docstring のテンプレートは ReST にかなり依存した書き方になっているんで、 sphinxcontrib-emacs が 「ReST やっぱり辞める。ごめんね。」ってなった場合に、大規模な docstring のスタイル変更が必要になります。doc/requirements.txt で書いてあるように github 経由で必要な sphix module をインストールしているんですが、最悪リビジョンを指定して使い続けることもできるんで、このまま移行してしまうという方法も一応考えられます。 docstring が充実するという意味では、 Emacs hacker な人たち的にはプラスだと思いますが、二度手間になる可能性があるのを考えるとあまり推してしまってはまずいかな、とも思います。

私の提案としては、こんな感じです（楽さを重視）：

1. Document deferred using sphinxcontrib-emacs #16 は docstring 以外のドキュメントの移行が終了次第マージ。
2. リリース待たないで「実験的な公開」ってことにしてAPIドキュメントも公開。ただし、 docstring の README からの移行は（既にされたものを除いては）しない。
3. docstring テンプレは sphinxcontrib-emacs のリリース後に考える。
4. @kiwanami さんが cacoo か何かでコールバックチェーンを図解する的なワクワクする図を書いてそれをドキュメントのトップに置く→ハッカーニュースとかに投稿する→deferred.el 大勝利

[kiwanami]

手っ取り早くという事で、日本語のissue、いいと思います！
@tkf さん、いつもありがとうございます。

docstringにリッチに書くのは嫌いではないです。Javadocもたくさん書いて来ましたし、文芸的プログラミングも方針としては好きです。（ソースコードという一次元的なシリアライズフォーマットが悪いのであって、Symbolのスロット的にいろいろ入れられる仕組みだといいのかなと思います。）
sphinxcontrib-emacs、もうかなり普通に動いているようですので、このまま使ってもいいかなと思っては居ます。mdもrstも、普通にテキストで見てもhtmlほどは気持ち悪くないと思っていますが、
問題があるとすればemacsのhelpとかautocompleteのdocオーバーレイで見てどうかという問題ぐらいでしょうか。

あと、@kozo2 さんも触れられていましたが、気になるのは言語の切り替えのところです。
APIはかなり安定してきているので、別管理でもいいんですが、なにかいい方法があればいいなと。

マージ方針については、 @tkf さんの方針で良いと思います。
そうすると、cherry-pick する必要があるのかな。

なかなか時間がなくて、とりあえずのコメントでした。
docstringを書き直すコストをちょっと考えてみます。

[tkf]

emacsのhelpとかautocompleteのdocオーバーレイで見てどう

ReST は 「raw text で見ても WYSIWYG」 が設計方針だと思うので、テキストをまったく弄らないでハイライトだけする *Help* のレンダリングと相性は良いと思います。

sphinxcontrib-emacs、もうかなり普通に動いている

deferred.el のドキュメントだと地雷踏んでないっぽいんですが、私が別で試したところによると色々踏みまくってまだ本格的には使えないなあという印象でした。 sphinxcontrib-emacs の issue のタイトルだけザックリ見るか、 http://emacs-python-environment.readthedocs.org を見て変なところ探して見て下さい。

言語の切り替え

en/ja の切り替えですか? RTD の URL よく見たら多言語対応してるみたいですね。リポジトリ分けたほうがやりやすいんじゃないかと思うんですが（例えば日本語ドキュメントならコミットも日本語で書ける）、それだと RTD が対応出来ない可能性もありますよね。

RTD の多言語対応やったことないんでどう設定するかよくわからないんですが、 @kozo2 さんご存知ですか？

そうすると、cherry-pick する必要があるのかな。

私の方針だと、 cherry-pick 必要ないと思います。docstring の変更を取り除いてからマージという方針だと cherry-pick 必要ですね。

[kiwanami]

年度末でつまってて、反応遅くてすみません。
なるほど。cherry-pick 必要無さそうなら、動作は変わらないはずですし、もうmergeしちゃおうと思います。

[tkf]

まだ他の PR をマージしないなら、急がなくて良いと思います。あと、 (1) docstring 以外の移行は @kozo2 がほとんどされてると思うんですがそれの確認と、(2) 移行した部分を README から削除するかどうかの決定と、 (3) README や github からリンクするかどうか（＝オフィシャルに公開？）の決定をしたほうが良いと思います。README からリンクするなら、 autodoc で生成した API のページに "warning: this page is experiment" とか何か書いておいたほうが良いと思います。

[kiwanami]

了解です。内容確認しています。

[kiwanami]

すいません。まとまった時間が取れてなくて、今週末まで少々お待ちを。。。

[tkf]

じっくり待っていて良かったのかもしれません。 sphinxcontrib-emacs のマークアップから、少なくとも最初のリリースからは ReST サポートが外れるみたいです。
ttps://github.com/flycheck/sphinxcontrib-emacs/issues/6#issuecomment-39457156

ReST サポートが無くなるってことは、docstringのフォーマットにあまり拘らなくて良くなります。

[kiwanami]

なるほど。ReSTのサポート無くても、ReSTだとHelpも読みやすそうなので、すこしずつ移行していこうかなと思いました。
表のREADMEの体裁を整えてRTDにリンク貼るようにして、doc版をメインにしようかなと思っています。

[kiwanami]

みなさん、すいません。作文に追われて中断してました。読みなおして思い出します。。。