2012年6月15日金曜日

Sphinxのファイルの拡張子とか

うーん。Sphinxのファイルの拡張子って、.rstと.txtのどっちが良いんだろう?
Sphinxを仕事で使うようになって、いろいろモヤモヤとしてきたので、整理してみます。




txtの良い点
  1. デフォルト設定のままでエディタが起動する
  2. 新規作成が少し楽。右クリック→新規作成→テキスト ドキュメント
  3. 既存のメモ書きを移行しやすい
rstの良い点
  1. エディタの設定をtxtファイルを分けられる
  2. ブラウザからソースファイルを開くとき、エディタが起動する
  3. .. include:: するドキュメントの拡張子を.txtにできる

txtは、導入コストが低いのが利点で、rstは、よりヘビーに使うときに良い。

いろいろ迷いながら、今のところはtxtで作成中。
本当はrstにしたいけれど、誰かに引き継ぐときのことを想像すると、txtになっちゃうんですよね・・・。



ついでに、Sphinx関連の自分タスクを洗い出し。
  • 既存のドキュメントのヘッダを、StleGide に合わせる
  • conf.pyの標準化
    なるべく内部の記述を変えずに色々なドキュメントで使えるconf.pyを作る
    • 中間色をconf.pyで自動算出させて、テーマ変数を上書き
    • ドキュメント名や作成者名をどこかで1度定義するだけで、htmlhelpも修正されるようにする
    • ドキュメントの格納元がローカルドライブかネットワークドライブなのかで、テーマ変数を調整する
  • テーマの修正
    • BizStyleでサイドバー固定、サイドバー幅のテーマ変数化 →完了
    • BizStyleと修正部分の分離
    • htmlから直接ソースファイルを開けるようにする → IEのみ完了。他はそのうち。
    • make htmlhelp対応
    • IE7でサイドバーの表示が少しおかしいのを直す
  • ドキュメントのプロトタイプの作成(業務情報を削除し、他でも使えるドキュメントを作る)
    • プロトタイプの作成
    • 作成したプロトタイプの公開
やれることはいっぱいあるなぁ・・・。

まずはプロトタイプを作ったほうが良いんだろうなぁ。
フィードバックもらえそうだし、テーマの修正も楽になるし。
(本物のドキュメントは育ちすぎていてビルドに時間がかるんですよねー)

ただ、conf.pyにタイトルとかの業務情報があると、
プロトタイプでconf.pyを修正したのを、本番ドキュメントに取り込み難いんですよね・・・。
でも、iniファイルをpythonで読み込みとかめんどいなぁ。

ん?
con.pyの中で from conf_ex import * とかやって、業務情報をconf_ex.pyに外だしとかどうだろう?
ちょっとやってみよう。

そもそも、conf.pyでテーマ変数をいろいろいじって頑張らせているのが間違いの始まりな気がしますが、拡張作るの面倒くさそうなので・・・。

0 件のコメント:

コメントを投稿