ラベル

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

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

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

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



    2. $ mkdir sphinx_text && cd sphinx_test



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



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



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



    4. $ 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
-----



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


    5. $ 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.


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


    6. $ 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/

ラベル:

人気の投稿