Sphinxの過去と、未来

著者

Georg Brandl

日付

2012/12/25

原文

Sphinx, past and future

翻訳

@r_rudi,@shimizukawa

このエントリーは日本語のSphinx Advent Calendar 2012に参加してくれないかというリクエストに応えて書いています。彼らはすごいよ!彼らは今年Sphinx Conferenceを開催して、イベントには70人もの人たちが集まったんだ!

Sphinxはいまや5歳になってるし、たぶん今までの歴史を振り返り、将来を語るのに良い時期じゃないかな。

このプロジェクトは2007年前半のいつ頃かに始まった。この投稿は私がPythonメーリングリストで見つけた中で一番古い。この時、Pythonのドキュメント作成のためのソースはLaTeXで書かれていた。私は科学的な文章を書くときには絶対LaTeXを使うぐらい好きだけど、その時(今もだけど)思ったのは、LaTeXはコードのドキュメントを書くには適していないってこと。あれは明らかにマークアップ言語ではないし、ドキュメントへの協力を躊躇させてしまう。それで我々はいつもいろんな形式のテキストを受け取るのに苦しんでいたんだ。

また、そのソースは簡単には使えなかったし、HTMLページ(しかもそのHTMLページにはほとんどのユーザにエラーが出ていた)からドキュメントソース中のファイルへのマッピングは分かりにくかった。あ、そのときソースからHTMLに変換するのに使っていたツールチェインについては聞かないで。(これはPython使いがハックしたいと思わない例の4文字の言語と密接に関連してた)

私は、その頃一部で使われ始めていたreStructuredTextとその実装の「docutils」を基盤としたコードを書いて、この状況を変えようとしていた。reSTはたぶん一番きれいなマークアップ言語ではないだろうけど、その時は(そして今も)いくつかの要求を満たしていたんだ。

  • 軽量なマークアップ(シンプルで、読むのに「邪魔」になる文字がない)

  • 簡単に拡張できる (codeでもマークアップでも)

  • Python実装がある

  • Pythonと強い結びつきがある (reSTはいくつかのPEPでマークアップ言語として指定されている)

新しいフォーマット(それとArminが作った新しい「グリーンな」デザイン)はたくさんの「+1」を受け取り、新しいツールチェインがPython-devで受け入れられた。それで、8月に私はPythonドキュメントをすべて変換したんだ。(ところで、あれは初期のPython 3000の作業をしてる真っ最中だったんだ。これに関してはまた別の興味をそそられる物語があってね…)いくつかの機能はまだなかったし、チャプター番号の自動採番とか実装に長い時間がかかった機能もあるけどね。

こうしてPythonは素敵で輝いている新しいドキュメンテーションツールを手に入れ、たくさんの人が「うちでも使える?」って聞いてきた。私はそんな反応があるとは思ってもなかった。なんでかというと「古いLaTeXシステム」は公開されていたけれど、誰もそれを使っているようには見えなかったからね1。(事実、今思い返してみても、誰がLaTeXシステムを使っていたか本当に思い出せないよ。もし覚えていたら教えてね!)

1

訳注: ドキュメントを書きたがっている人がいるとは思っていなかった

それでも、Pythonicでドキュメント変換を簡単にしたシステムは、良いものを作ったように見えたんだ。すぐにSphinxという名前をつけたプロジェクトが誕生した。今は、他で使われていないもっと良い名前を見つけたいと願ってるけど、その時はpython.orgのWebサイトで使っている "Pyramid" システムとかけてたんだ。CMU SphinxSphinx searchは両方共私は使ったことがあるし、どちらもすごいプロジェクトだ。彼らには謝らなければならないね。(おもしろいことに、Sphinx searchも「ホルスの目」のロゴを使ってるんだ。いや、私はその時ほんとにそのことを知らなかったんだよ)

そういうことはあるけど、Sphinxはあっという間に人気になり、私はとてもびっくりしたよ。Sphinxを使っているプロジェクト編集履歴を見てみてよ。Django、numpy、matplotlibなどのいくつかの大きなプロジェクトはとても早い時期から導入したね。

コードベースをPython用に完全に合わせていたので、全部のPython固有のコードやハードコード文字列を取り除くのにはかなり時間がかかったよ。でも、一旦その作業が終わると、拡張機能を素早く実装できるようになったんだ。Pythonが使っていないけど他ので使っている一番大きな機能はautodocだね。私は、autodocはドキュメントの自動生成手書きとの間のほぼ完璧なバランスを取れていると思っているから、とても大事な機能だね。自動生成されたものは大抵醜い獣となり、すでに良く知っているソフトウェアでなければ理解できない程度になる。チュートリアルはソースコードの中にいれたくないから、置き場所がない。手書きのドキュメントは書くのが退屈で山のように書く必要があるけれど、大体の場合これがあるとドキュメントが読みやすくて分かりやすくなるから、個別の解説文はソースコードの中に入れられるようになる。だからPythonはこの方法を取っているんだ。

autodocは理にかなってると思えるこれら両方の様式を兼ね備えている。ドキュメントの全構造を手で書き、必要に応じて解説文を書き、実装の観点からではなく論理的な観点からAPIの説明を分かりやすく並べ変える。それから、各APIのdocstringをドキュメントに埋め込む

この何年かでautodocの他に、たくさんの機能が追加された。コードハイライトは特別な機能ではなくなったね。

  • intersphinxで複数のドキュメントをつなぐ

  • doctestを含めて、Sphinxから実行できるように

  • HTML テーマは標準のもの以外にもいくつか増えてきたね

  • 数式ダイアグラムといったメディアのサポート

  • TexinfoやePubなどのたくさんの出力フォーマットをサポート

これまでのマイルストーンはここで見れるよ。「大きな」 1.0リリースは2010年にdomainの追加とともに行われた。domainはPython以外の言語へとSphinxの範囲を広げたんだ。でも期待したようには世界全体を取れていない… まだ、ね :)

最近までSphinxはわりと独裁的に開発されていた。あ、それまでも多くの貢献があったんだよ!2010年には、Sphinxにサマーオブコード学生達が何人かやってきてPython 3の移植、国際化、Webアプリケーションインタフェースといった機能を開発してくれたんだ。でも、最終的には私は全ての修正やプルリクエストに目を通してきた。でも、私の大学院生活が始まった時、大量のやるべき事の前に、自分の人生がとても短い時間でしかないことが分かったんだ。

こういった事があって、今年、Sphinxの未来を作っていく開発者のチームを編成したんだ。これまでのところ、以下の人たちにpush権限を与えている。

  • Ervin Hegedüs

  • Jon Waltman

  • Kevin Hunter

  • La Min Ko

  • Nikolaj van Omme

  • Robert Lehmann

  • Roland Meister

  • 清水川 貴之

私は彼ら全員にとても感謝しています。また、新しいsphinx-dev MLを開発者の連携のために立ち上げ、それまでその名前で利用者向けのサポートを行っていたMLをsphinx-users MLに移した。この開発者チームの編成により物事が動き始め、たくさんのバグといくつかの新機能を搭載した1.2がもうすぐリリースされることになった。

これからどうするのかって?私は機能的には十分だと思っているけど、いつだってなにかしら不足はあるものだね。そう、私と開発者チームはこれからの開発でこんなことを考えている。

  • 私が完全な自動化をあんまり好きではないため、自動ドキュメント生成のsphinx-apidocはそんなに頭が良くない。でも、他の人は興味があると思う。

  • Autodocはもっとデバッグが簡単になるべき。例えば、中間生成されているreSTにアクセスできるべき。

  • 国際化機能はそんなに広く使われていない。おそらく実装にいくつかの欠点がまだあるから。我々は欠点を修正し、できる限り多くの言語にSphinx自身のドキュメントを翻訳する事で、良い例を作っていきたい。

  • Webアプリケーションサポートはもっと簡単に使えるようになるべき。例えばコメントを含めたりユーザーからの提案を簡単にしたり。

  • docutilsは数式やコードハイライトなど、Sphinxが開拓してきた多くの機能をサポートしようと成長してきた。私はこういった、違うマークアップで同じ機能を提供している部分を統合したいと思っているよ。

今はこんなところ。メリークリスマス!