究極のドキュメント管理を考える その6 sphinxのインストール

sphinxはpythonで書かれた、ドキュメントジェネレータです。

ドキュメントをreStructuredText形式で書いておけば、
コマンドを実行するだけで、HTMLやLaTexに書き出してくれる優れものです。

インストール手順は以下
$ sudo aptitude install python-sphinx
 使い方は、
  1. ドキュメント保存のためのディレクトリ作成



  2. $ mkdir sphinx_text && cd sphinx_test
    



  3. /usr/bin/sphinx-quickstartを実行して質問に答える



  4. $ sphinx-quickstart
    英語で質問されるので、答える。
    基本、Enter連打でOKだが、「rstソースとジェネレートファイル置き場を分けるか?」
    という質問に対して、Yesにした方が管理しやすいのでおすすめ
    



  5. 2.でできた ***.rst を編集したり、新しく ***.rst を追加したりする



  6. $ tree
    .
    |-- Makefile
    |-- build
    `-- source
        |-- conf.py
        `-- index.rst
    
    2 directories, 3 files
    $ emacs source/my.rst source/index.rst
    my.rstを新規追加
    index.rstには、my.rstに遷移できるようにリンクをつける
    -----
    .. toctree::
       :maxdepth: 2
    
       my
    -----
    



  7. make html でHTMLをジェネレート


  8. $ make html
    mkdir -p build/html build/doctrees
    sphinx-build -b html -d build/doctrees   source build/html
    Sphinx v0.4.2, building html
    trying to load pickled env... done
    building [html]: targets for 1 source files that are out of date
    updating environment: 0 added, 1 changed, 0 removed
    reading... index 
    pickling the env... done
    checking consistency...
    writing output... index 
    finishing... 
    writing additional files...
    copying static files...
    dumping search index...
    build succeeded.
    
    Build finished. The HTML pages are in build/html.
    


  9. web serverのドキュメントルートにコピーすればHTMLを確認できます


  10. $ cp -R build/html/* /var/www/nginx-default/sphinx/
    
といった流れです。
できたページが、


こんなページになります。
デフォルトでこのような見た目のページができて、かつ、
検索機能も付いています。
検索機能はjavascriptで実装されているので、
CGIの準備は必要ありません。

検索機能について、や、カスタマイズ方法については
また別途ブログに書きたいと思います。

参考:
http://sphinx.shibu.jp/index.html
http://plaza.rakuten.co.jp/kugutsushi/diary/200803230001/