sphinxをインストールしてビルドするまで

今まで気になっていたsphinxというツールをインストールしてみた。

これはpython用のドキュメントツールらしいのだが、pythonさえ入っていれば使うことができる。

pythonが入っていないとインストールできないので

自分のPCにインストールされているかを確認する。

$ python --version

Windowsでのインストールは下記URLのように行った。

プロジェクトの作り方等は下記サイトを参考にして作成した。

中でも重要な部分はルートパス指定とソース・ビルドフォルダの分離だと思う。

sphinx-quickstartに作成したいフォルダ名を入力する。

$ sphinx-quickstart report

こうすることで、作成したフォルダ名の中に構成ファイルなどを作ってくれる。

沢山のドキュメントをSphinxで作るときには便利かもしれない。

sphinx-quickstartで実行した際、以下のような質問をされる。

> Separate source and build directories (y/N) [n]:

ここでy(yes)を入力すると、編集するファイルをsourceというフォルダに分けてくれる。

特にこだわりがなければ、yにしておくのが楽かと思う。

日本語をテキスト内に入れたときに文字化けが発生していた。

sphinxの文字化けで検索したところ、対策が下記URLにあったので施した。

しかし、私の場合はそれでも直らなかった。

よくよく確認してみると、index.rstのファイルの文字コードがShift-Jisになっていた。

そりゃ出ませんわな！(*´ω｀*)

ということで、文字コードをUTF-8に変更して保存し、ビルドした。

そうしたらうまく日本語も表示できるようになった。

書いた感覚でしかないが、これはMarkdown形式とは違う書き方だ。

結構特殊な記述法なので、慣れるのに時間がかかると思う。

またpythonのツールだからか、インデントがそろってないとビルドができないなど、制約も比較的多い。

それも含めて学習コストは高いと思っている。

まぁ、設計書をこっちで書いた方がいい気がした。

やはりテキストで書いてある以上、差分がツールで見れるのは大きい。

頻繁に変わるものをエクセルのようなバイナリファイルで管理するのは難しいと思う。

差分をパッと見れないから、どこが変わったかも分かりにくいから管理は不可能だ。

しかし、書きやすさは明らかにエクセルの方が上だ。

どうしてもビルドして確認する行為がいる以上、作るのは手間がかかる。

メンテナンスするファイルでなければ、エクセルで作った方がいいのかもしれない。

もしくは、sphinx形式にする変換ツール等あれば、とっつきやすくなるかもしれない。