Sphinx アドベントカレンダー22日目

by 2JHari On December 21st, 2012

こちらに訂正版書きました。不手際があり、すみません。
http://jharrison.blog.com/?p=24


こんにちは、クレイジーなHarrison
です(`・ω・´)ゞ 巷ではブロックダイアグを使うようなアホだと言われていますが、いかがおすごしでしょうか。寒くなりました。何やらアドベントカレンダーというものが続行中のようであり、これに滑り込まないわけには行かないと思った次第なので飛び込みます⊂(゚Д゚⊂⌒`つズザー

なお、今回技術的な話はしません。主にどう使っているかという話をします。知識がない私はまさかりレーダーに狙われる生活をしており、技術的な発言をしようとすると四方八方からまさかりが飛んでくるおそれがあるのです。今年の◯◯ JPプロレス場でも、周囲に飛び交っているまさかりを見て震え上がりました。その恐怖の中、これを書きます。

======================================
Sphinxをなぜ使うの?
======================================
ファイルを分割して書けるから。何よりもこれです。HTML出力とか翻訳するとき役立つというのもありますが、やはりひとつのファイルでなくてよいのは助かります。メモだとか、ノートだとか、そういったのがブワーっと文字で溢れてると、結構うんざりします。
キチンとレポートやら論文を書こうとしたときはこれが困るんです。整理がしにくい。論理的に書くとは、整理して構造を意識して書くということだと思います。

~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
構造的に書くとは
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
ピラミッドを意識して書くということです。マインドマップを思い浮かべるといいかもしれません。雰囲気的には近いです。「論理トレーニング」で述べていることにせよ、ベースにあるのはきちんと分解して、構造を把握するということだと思います。index.rstというひとつのファイルからどう分割してそれぞれのファイルをつなげてくかについてはPyプロを参照するといいと思います。

構造を意識するとき、どの文章でも着目すべき点はこの3つです。それは、主張、根拠、その2つをつなぐ導出。メモやらなんやらで文字が溢れかえっていると、これらがとてもつかみにくくなります。

ちょっと詳細に述べてみます。こんな箇条書きのメモがあったとしましょう。
--------------------------------------
*壁ドン こみやさんに
 *はり クレイジー
 *ぶろっくでぃあぐ
--------------------------------------
いや、どんなメモですか。これを整理すると、こんな図↓になります。
http://twitter.yfrog.com/h7llaqp

ここから、文章を書きなおすと次のとおりです。
「ハリソンはクレイジーである。理由は2つある。第一に、blockdiagを使っているからであり、第二にこみやさんに壁ドンされたいからである( 〃▽〃)」
と、こんな感じに整理できます。意味はわかりませんが、整然とした気がします。

そんなわけで、一定程度を超える文量のものを、理路整然と書くことを意識するならSphinx使ってみるのもありですよというお話でした。

〜〜〜〜〜余談〜〜〜〜〜〜〜
そういえば、去年かな? "ドキュメントを書くツール"と聞いて、「こあい!!」「ドキュメントって何??((((;゚Д゚))))」と身構えてました。でも、ハッカソンにこっそりお邪魔するようになり、次第に質問を投げまくったりして(すませんでした)、その不安は消えました。(特にこみやさんにはありとあらゆる場所でかなり質問させていただきましたm(_ _;)m)

みなさん、文章書いた経験はありますよね?何枚も書いてるうちに、消しゴムはこれがいいとか、こっちのシャーペンよりこのシャーペン使いたいとか思うようになって。そんなのと同じで、パソコンの鉛筆にこだわるぐらいのつもりで気楽に構えるといいんじゃない?あ、こんなうかつなこと言うとマサカリがうわなにをすくぁwせdrftgyふじこlp
〜〜〜〜〜〜〜〜〜〜〜〜〜〜

======================================
参考文献とか
======================================
・The Pyramid Principle by Barbara Minto
 ←ピラミッドとは主にここで紹介されている概念です。訳書もありますが、原書の英文はとてもシンプルなので、こっちを読む方がいい気がします。

・新版 論理トレーニング 、論理トレーニング101題 by 野矢 茂樹 
 ←主にこの2冊での主張は、特に後者ででてくる問題でも、分解して整理するということにつきるのではないかという印象です。具体的な仕方などはこの辺の本で。

・Pythonプロフェッショナルプログラミング by ビープラウド 
 ←Sphinxに関することは、ドキュメントそのもののことから導入などまで、とりあえずまず参考にするとよさげ。内容が1番まとまってるので。

https://twitter.com/usaturn/status/280227267832074240
 ((*゜ω゜*))

~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
僕が使い始めるまで参考にしたものなど
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

・Sphinx
& blockdiag Advent Calendar(全部俺) : ATND
http://atnd.org/events/22450
 ←昨年のこみやさんのもの。導入〜翻訳についてこの辺を参考にしました。

・"Sphinx
をはじめよう :: ドキュメンテーションツール スフィンクス Sphinx-users.jp" http://sphinx-users.jp/gettingstarted/index.html
 ←導入で1番参考にした場所です。

・kashew_nuts-tech
: reST→PDF出力の環境を整備した。 http://kashewnuts-tech.blogspot.com/2012/06/restpdf.html
 ←困ったとき助かりました(*´ω`*)
;・"発表資料 ::="" ドキュメンテーションツール="" スフィンクス="" sphinx-users.jp"="" http:="" sphinx-users.jp="" doc.html ←Sphinxとは何?という人がまず見るといいと思うもの。「ドキュメントを作りたくなってしまう魔法のツールSphinx」のスライドは情報がつまっていて、とても役立ちました。

・"Overview — Sphinx 1.1.3 documentation"
http://sphinx-doc.org/
 ←初心者の僕がつまづいたのは、導入と日本語周りです。導入については、ここに書いてあるように"easy_install
-U Sphinx"と入れて解決しました。「-U」のおかげでうまくいったみたいです。うさたーんさんに教えていただきました。

======================================
キャッチボール
======================================
@r_rudi ヽ(・ω・ヽ)はいよっ
 ( ノ・・)ノパスッ! @tboffice