Context Navigation

Sphinx でビルドしたドキュメントを公開するためのアプリケーション、 Lionet

Sphinx でビルドしたドキュメントを公開するための Django アプリケーション、 Lionet を公開しました。

http://pypi.python.org/pypi/lionet/ , BSD ライセンス。

(2009/06/24 ymasuda)

最近、 Sphinx を使ってドキュメントを提供するソフトウェアプロジェクトが増えてきましたね。テキストファイルから簡単に HTML や PDF のドキュメント配布物を作れるので、とても便利。元が reST なので、メンテナンスや翻訳もしやすいです。

さて、Sphinx の HTML ビルダは、全てのコンテンツを相対パスで参照する HTML を生成するので、ビルドしたドキュメントはオフラインでも参照できます。私も、自分の使うソフトウェアのドキュメントはほとんどビルドして手元に持っているんですが、ドキュメントが増えてきて、最近ちょっと不便に感じています。というのも、

Sphinx のビルダがテンプレートの適用までしてしまうので、プロジェクトごとに見栄えが違っていたり、デフォルトの（個人的にはあまり好きじゃない）レイアウトで表示される。

それぞれのドキュメントに検索インタフェースがついているんだけど、いちいち検索フォームにたどり着くのが面倒。できればまとめて検索したい。

というわけで、そんな やや個人的な 不満を解決するために作ってみたのが、 lionet という Django アプリケーションです。

Sphinx には、HTML ビルダの他に、pickle ビルダが付属しています。 pickle ビルダは、テンプレート適用前のコンテンツデータ（本文やメタデータ）を pickle 化して、ファイルに保存してくれます (もともと pickle ビルダは、 sphinx-web という Web アプリケーションでドキュメントを公開するときのデータストアとして使われていたようですが、今の Sphinx には sphinx-web はありません)。lionet は、この pickle データを使ってコンテンツを ちょっとだけ 動的に生成します。

主な機能

ドキュメントのコンテンツや、索引・モジュール索引は、本文とメタデータ情報をもとにテンプレートエンジンで生成されます。したがって、ドキュメントのメタデータやビルド環境データをテンプレート上で加工して出力できます。
簡単な検索インタフェースがついていて、コンテンツを検索できます。
複数のドキュメントプロジェクトを管理でき、サイト全体のSphinxドキュメントコンテンツに対する総索引・総モジュール索引・検索を実行できます。

使い方

Sphinx を使って、好きなドキュメントを pickle ビルダでビルドします。

$ cd your/sphinx/docs/
$ make pickle

通常、この操作で、Sphinx は your/sphinx/docs/_build/pickle に pickle ビルドを生成するはずです。

django のプロジェクトディレクトリの urls.py に lionet の urlconf を組み込みます。単一のドキュメントしか扱わないのなら、 lionet.standalone_urls を組み込むだけ。 settings.py に手を加える必要はありません。

urlpatterns = ('',
   ...,
   (r'^lionet_standalone', include('lionet.standalone_urls'), 
    {'document_root': '..,your/sphinx/doc/_build/pickle'}),
   ...)

複数のドキュメントを扱いたいのなら、django のアプリケーションとしてインストールします。

settings.py
---
INSTALLED_APPS = (
  ...,
  'lionet',
)

urls.py
---
urlpatterns = ('',
   ...,
   (r'^lionet_multiple', include('lionet.multiple_urls'), 
    {'document_root': '..,your/sphinx/doc/_build/pickle'}),
   ...)

syncdb を忘れずに！ admin で、ドキュメントディレクトリを登録しましょう。 name にはドキュメントディレクトリを区別するパス (例: lionet_multiple/userguide/... の userguide)、 label にはドキュメントディレクトリを説明する短い言葉 (例: ユーザーズガイド)、 document_root には pickle ディレクトリを指定します。

/lionet_standalone/ または /lionet_multiple/(project_name)/ にアクセスしてみてください。 enjoy!

Download in other formats:

Plain Text