PyDoc はいい加減アレだし、そろそろ Sphynx 使いたいよねーと思っていたところに Sphinx+翻訳 Hack-a-thon があったので参加中。
作業ログ代わり兼Blogネタとしてやったことを記録していく感じ。
インストール
はいはい easy_install ドーーーーン!!
>easy_install sphinx
Sphinxを使ってみる
Pythonって何？という人のためのSphinxチュートリアルを参考に作業を進める
プロジェクトを作成する
Windows の場合、 $(Pythonのインストールディレクトリ)\Scripts\sphinx-quickstart.exe を使う。いろいろ聞かれるものの、ほとんどはとりあえずデフォルトで。プロジェクト名、Authorなどは適当に。
とりあえずビルドしてみる
$(Pythonのインストールディレクトリ)\Scripts にパスが通っていれば VS のコマンドプロンプトから起動しなくても大丈夫。
>make.bat html
ドキュメントを書いてみる
reStructuredText入門 を参考に。日本語でドキュメントを書く場合は、元の rst ファイルは UTF-8 で保存されている必要がある
例としては下のような感じ。ただし、セクションなどの記号は、特に標準というものはない。(!!)
========
タイトル
========
セクション
========
サブセクション
--------
サブサブセクション
^^^^^^^^
ドキュメント中で使用されていない記号が出てきたときに、それが随時セクションわけのための記号として登録されていく。
そのため、別のドキュメントで別のセクション記号が使用されていてもOK。
ただし、ドキュメントをインクルードする場合はそれぞれのドキュメントで仕様を統一しておく必要がある。
所感
- やっぱりタグでドキュメントを書くのは21世紀になってやることなのカー?という気持ちが強い
- Windows でも環境構築をするのは簡単
- WYSIWYG で Web インターフェースなエディタが欲しいナー(ﾁﾗﾁﾗ