Changes between Initial Version and Version 1 of LionetDjangoApp


Ignore:
Timestamp:
06/24/09 03:36:20 (9 years ago)
Author:
ymasuda
Comment:

--

Legend:

Unmodified
Added
Removed
Modified
  • LionetDjangoApp

    v1 v1  
     1= Sphinx でビルドしたドキュメントを公開するためのアプリケーション、 Lionet = 
     2 
     3Sphinx でビルドしたドキュメントを公開するための Django アプリケーション、 Lionet を公開しました。 
     4 
     5http://pypi.python.org/pypi/lionet/ , BSD ライセンス。 
     6 
     7(2009/06/24 ymasuda) 
     8 
     9最近、 Sphinx を使ってドキュメントを提供するソフトウェアプロジェクトが増えてきましたね。 
     10テキストファイルから簡単に HTML や PDF のドキュメント配布物を作れるので、とても便利。 
     11元が reST なので、メンテナンスや翻訳もしやすいです。 
     12 
     13さて、Sphinx の HTML ビルダは、全てのコンテンツを相対パスで参照する HTML を生成するので、ビルドした 
     14ドキュメントはオフラインでも参照できます。私も、自分の使うソフトウェアのドキュメントは 
     15ほとんどビルドして手元に持っているんですが、ドキュメントが増えてきて、最近ちょっと不便 
     16に感じています。というのも、 
     17 
     18 * Sphinx のビルダがテンプレートの適用までしてしまうので、プロジェクトごとに見栄えが 
     19   違っていたり、デフォルトの(個人的にはあまり好きじゃない)レイアウトで表示される。 
     20 
     21 * それぞれのドキュメントに検索インタフェースがついているんだけど、いちいち検索 
     22   フォームにたどり着くのが面倒。できればまとめて検索したい。 
     23 
     24というわけで、そんな ''やや個人的な'' 不満を解決するために作ってみたのが、 lionet  
     25という Django アプリケーションです。 
     26 
     27Sphinx には、HTML ビルダの他に、pickle ビルダが付属しています。 pickle ビルダは、 
     28テンプレート適用前のコンテンツデータ(本文やメタデータ)を pickle 化して、ファイルに 
     29保存してくれます (もともと pickle ビルダは、 sphinx-web という Web アプリケーション 
     30でドキュメントを公開するときのデータストアとして使われていたようですが、今の Sphinx 
     31には sphinx-web はありません)。lionet は、この pickle データを使ってコンテンツを 
     32''ちょっとだけ'' 動的に生成します。 
     33 
     34== 主な機能 == 
     35 
     36 * ドキュメントのコンテンツや、索引・モジュール索引は、本文とメタデータ情報をもとにテンプレートエンジンで生成されます。したがって、ドキュメントのメタデータやビルド環境データをテンプレート上で加工して出力できます。 
     37 * 簡単な検索インタフェースがついていて、コンテンツを検索できます。 
     38 * 複数のドキュメントプロジェクトを管理でき、サイト全体のSphinxドキュメントコンテンツに対する総索引・総モジュール索引・検索を実行できます。 
     39 
     40== 使い方 == 
     41 
     42Sphinx を使って、好きなドキュメントを pickle ビルダでビルドします。 
     43{{{ 
     44$ cd your/sphinx/docs/ 
     45$ make pickle 
     46}}} 
     47通常、この操作で、Sphinx は your/sphinx/docs/_build/pickle に pickle ビルドを生成するはずです。 
     48 
     49django のプロジェクトディレクトリの urls.py に lionet の urlconf を組み込みます。 
     50単一のドキュメントしか扱わないのなら、 lionet.standalone_urls を組み込むだけ。 settings.py に手を加える必要はありません。 
     51{{{ 
     52urlpatterns = ('', 
     53   ..., 
     54   (r'^lionet_standalone', include('lionet.standalone_urls'),  
     55    {'document_root': '..,your/sphinx/doc/_build/pickle'}), 
     56   ...) 
     57}}} 
     58 
     59複数のドキュメントを扱いたいのなら、django のアプリケーションとしてインストールします。 
     60 
     61{{{ 
     62settings.py 
     63--- 
     64INSTALLED_APPS = ( 
     65  ..., 
     66  'lionet', 
     67) 
     68 
     69urls.py 
     70--- 
     71urlpatterns = ('', 
     72   ..., 
     73   (r'^lionet_multiple', include('lionet.multiple_urls'),  
     74    {'document_root': '..,your/sphinx/doc/_build/pickle'}), 
     75   ...) 
     76}}} 
     77 
     78syncdb を忘れずに! admin で、 ドキュメントディレクトリを登録しましょう。 
     79name にはドキュメントディレクトリを区別するパス (例: lionet_multiple/userguide/... の  userguide)、 
     80label にはドキュメントディレクトリを説明する短い言葉 (例: ユーザーズガイド)、 
     81document_root には pickle ディレクトリを指定します。 
     82 
     83/lionet_standalone/ または /lionet_multiple/(project_name)/ にアクセスしてみてください。 enjoy! 
     84    
     85