10日目のエントリは@usatarn さんの本家 Sphinx Advent Calendar 2012 10日目です。
はじめに
なぜ、普段JavaやGroovyしか書いていない私が、このAdvent Calendarに参加したのかは、@usatarnさんとの以下のやり取りでした。
#sphinxjp の人からconnpassのページを開けと言われるがままに開いたら今度はボタンを押せとか言われました。気付いたら「Sphinx Advent Calendar 2012」に強制参加させられていたので皆さんも宜しく！いやあSphinxの人こわいわ～ #pyfes
— うさたーんさん (@usaturn) 11月 24, 2012@usaturn 頑張ってください。
— とーますさん (@grimrose) 11月 24, 2012@grimrose 一緒にやりましょう！
— うさたーんさん (@usaturn) 11月 24, 2012@grimrose えっ
— うさたーんさん (@usaturn) 11月 24, 2012まぁ、ネタがなかった訳ではなかったので、参加しました。
おお、参加ありがとうございます！ #sphinxjp RT @grimrose @usaturn え？
— うさたーんさん (@usaturn) 11月 24, 2012というわけで、よろしくお願いします。
導入経緯
いわゆる手順書を作ったことがある方が、どれくらいいらっしゃるのか分かりませんが、
マイクロソフト謹製のオフィススイートで何らかの手順書を作られた方は、だいぶいらっしゃると思われます。
そんなあなたにSphinxで手順書を作ってみましょうというお誘いです。
今回は、ミドルウェアのインストールの手順を書いた時のことを書いてみます。
手順書を作成する時に使ったのは、以下のツールです。
初めてpythonで書いたのは、このスクリプトでした。
全くpythonを知らなかった私に教えて下さった@wonderful_panda さん、ありがとうございました。
もちろんSphinxのインストールは、Sphinxのインストールを参考にさせていただきました。
Windowsへのインストールは、本当に簡単でした。
準備は、これだけです。
あとは、実際の手順をメモしたり、実行したコマンドをコピーしたテキストなりを開いておきながら、手順書の体裁を整えて行きました。
マイクロソフト謹製のオフィススイートで何らかの手順書を作られた方は、だいぶいらっしゃると思われます。
そんなあなたにSphinxで手順書を作ってみましょうというお誘いです。
今回は、ミドルウェアのインストールの手順を書いた時のことを書いてみます。
手順書を作成する時に使ったのは、以下のツールです。
- Sublime Text 2
- FireFox or Chrome + auto reload系のプラグイン
- 10秒ごとに「make html」するpythonスクリプト
- pythonスクリプトを実行するbatファイル
初めてpythonで書いたのは、このスクリプトでした。
動いたっぽい。 import time,oswhile True:os.system("make html")time.sleep(10)
— とーますさん (@grimrose) 10月 24, 2012全くpythonを知らなかった私に教えて下さった@wonderful_panda さん、ありがとうございました。
もちろんSphinxのインストールは、Sphinxのインストールを参考にさせていただきました。
Windowsへのインストールは、本当に簡単でした。
準備は、これだけです。
あとは、実際の手順をメモしたり、実行したコマンドをコピーしたテキストなりを開いておきながら、手順書の体裁を整えて行きました。
メリット
Sphinxでのメリットは以下の点が、メリットではないかなと考えます。
reStructredTextのフォーマットに従っていれば、それなりにテーマに沿った形で後で出力してくれるので、書くときは、書きたいことに専念できます。
手順書は後々に、設定が変更になった場合、以前に書かれていたことが分からないと「なぜこのような設定になった」のかが見えにくくなります。
しかし、reStructredTextは、テキストベースなので差分管理をバージョン管理システムに任せることができます。
バイナリでしか管理できない某ファイルで悔しい思いをした人は、いっぱいいらっしゃると思われます。
Sphinxには、コードブロックが使えるので、コードをそのまま埋め込むことができます。
また、シンタックスハイライトを指定できるので、より見やすく出来るようになります。
マイクロソフト謹製のオフィススイートがインストールされてない環境(インストールされてない場合、大抵オフライン環境なのでViewerも落とせません…)であっても、htmlに吐き出せるので、最低限ブラウザさえあれば閲覧可能です。
- rstなので、ソース管理できる。
- コードブロックが使えるので、コピペする場合に見た目が分かりやすい
- 標準のテーマのhtmlであれば、別途readerが要らない
reStructredTextのフォーマットに従っていれば、それなりにテーマに沿った形で後で出力してくれるので、書くときは、書きたいことに専念できます。
手順書は後々に、設定が変更になった場合、以前に書かれていたことが分からないと「なぜこのような設定になった」のかが見えにくくなります。
しかし、reStructredTextは、テキストベースなので差分管理をバージョン管理システムに任せることができます。
バイナリでしか管理できない某ファイルで悔しい思いをした人は、いっぱいいらっしゃると思われます。
Sphinxには、コードブロックが使えるので、コードをそのまま埋め込むことができます。
また、シンタックスハイライトを指定できるので、より見やすく出来るようになります。
マイクロソフト謹製のオフィススイートがインストールされてない環境(インストールされてない場合、大抵オフライン環境なのでViewerも落とせません…)であっても、htmlに吐き出せるので、最低限ブラウザさえあれば閲覧可能です。
改善点
初めてSphinxに触ったので、以下の点にちょっと困りました。
後半になってPDFでも出して見ようとしてみたら、レイアウトが崩れたり、コードブロックのシンタックスハイライトがうまく設定されていなかったりと、いろいろ残念なことになってしまってしまいました。
もしかしたら、初めからPDFで出力するようにしておけば、もっといい結果になったと思います。
コードブロックの属性については、http://pygments.org/docs/lexers/を参考にさせていただきました。
これを見つけてからは、いろいろなコードを埋め込める様になりました。
- pdfで出力してみたら、ちょっと残念な結果に。
- 表示対象のコードがどのコードブロックの属性にすればいいのか、探すのに苦労した。
後半になってPDFでも出して見ようとしてみたら、レイアウトが崩れたり、コードブロックのシンタックスハイライトがうまく設定されていなかったりと、いろいろ残念なことになってしまってしまいました。
もしかしたら、初めからPDFで出力するようにしておけば、もっといい結果になったと思います。
コードブロックの属性については、http://pygments.org/docs/lexers/を参考にさせていただきました。
これを見つけてからは、いろいろなコードを埋め込める様になりました。
おわりに
私がおすすめするやり方は、以下の手順です、
そうすれば、マニュアルの引継ぎも変更履歴が追えるので楽になると思います。
まだ、私自身Sphinxを使い始めたばかりなのですが、いろいろなプラグインがあるみたいなので、試しつつ普段の仕事に役に立てばいいなと考えています。
というわけで、うまくお誘いできているか分かりませんが、ちょっとでも興味を持っていただければ、幸いです。
次は、@shibuさんのSphinx-Users.jpを作った時のお話です。よろしくお願いします。
- まず普段定型的に行ってる作業の手順を、Sphinxで書いてみる。
- 次に、DVCSと組み合わせて、差分管理してみる。
そうすれば、マニュアルの引継ぎも変更履歴が追えるので楽になると思います。
まだ、私自身Sphinxを使い始めたばかりなのですが、いろいろなプラグインがあるみたいなので、試しつつ普段の仕事に役に立てばいいなと考えています。
というわけで、うまくお誘いできているか分かりませんが、ちょっとでも興味を持っていただければ、幸いです。
次は、@shibuさんのSphinx-Users.jpを作った時のお話です。よろしくお願いします。
