Download

ダウンロードサイト:

http://michilu.googlecode.com/svn/trunk/helpdoc

$ svn co http://michilu.googlecode.com/svn/trunk/helpdoc
$ mv helpdoc myproject/helpdoc

Install

INSTALLED_APPS = (
    ...
    'myproject.helpdoc',
    ...
    'django.contrib.admin',
    ...
)

urlpatterns = patterns('',
    ...
    (r'^helpdoc/', include('myproject.helpdoc.urls')),
)

urlpatterns = patterns('',
    ...
    (r'^accounts/login/$', 'django.contrib.auth.views.login', dict(
        template_name = "admin/login.html",
    )),
)

Tuor

Django administration を開きましょう。 通常だと http://127.0.0.1:8000/admin/ でアクセスできます。 ログイン後の右上にいくつかのメニューが表示されています。

この中の documentation をクリックします。

いくつかのドキュメントの見出しが並んでいます。 一番上に Help Documentations が新たに追加されていますので、これを選択します。

左上のナビゲーションが HelpDoc になりました。 このページが helpdoc アプリケーションのメインページです。 まだ何もリストにありませんが、これから自由にドキュメントを追加していくことができます。

では、簡単に動作を確認するために あなた のアプリケーションにドキュメントを追加してみましょう。

$ ls -d1 **/docs
blog/docs
doc/docs
helpdoc/docs

いくつかのアプリケーションが既にインストールされているとします。 アプリケーションディレクトリのすぐ下に docs という名前のディレクトリを作成します。

HelpDoc のメインページをリロードすると、新しいメニューが追加されているはずです。

追加されたメニューをクリックしてみましょう。 「ページが見つからない」となりますが、壊れている訳ではありません。 なにしろまだドキュメントを書いていないですからね！ helpdoc は docs ディレクトリの中の index.txt を表示しようとします。

では何か書いてみましょう。

$ mkdir blog/docs
$ echo "TEST" > blog/docs/index.txt

テキストエディタで書き込みます。 docs/index.txt に保存します。 ここでは "TEST" と書き込んだ index.txt を表示してみます。

表示されましたね！ この要領でドキュメントを書いていきます。 フォーマットは、Djangoがサポートしている reStructuredText, Markdown, Textile と HTML が使えます。

もう少し実用的な例を見てみましょう。 よいサンプルがあります。

以下から Django オンラインドキュメント和訳 をダウンロードします。

• http://michilu.com/static/doc-ja/tarball/django-doc-ja-0.96.zip
• http://michilu.com/static/doc-ja/tarball/django-doc-ja-0.96.tar.gz
• http://michilu.com/static/doc-ja/tarball/django-doc-ja-0.96.tar.bz2

$ curl -O http://michilu.com/static/doc-ja/tarball/django-doc-ja-0.96.zip
$ unzip django-doc-ja-0.96.zip
$ mv django-doc-ja-0.96 myproject/myapp/docs

解凍し docs ディレクトリにリネームして配置します。

HelpDoc のメニューからアクセスしてみましょう。 これで オフラインでも ドキュメントを参照することができますね！

テキストフォーマットを指定する

テキストフォーマットを指定するには2つの方法があります。

urlpatterns = patterns('',
    ...
    (r'^helpdoc/', include('myproject.helpdoc.urls'), dict(
        markup = "rst", # reStructuredText
        # markup = "markdown", # Markdown
        # markup = "textile", # Textile
        # markup = "html", # HTML
    )),
)

テンプレートを指定する

ベースとなるテンプレートを指定します。 HelpDoc はマークアップテキストをレンダリングした結果を content 変数にいれてテンプレートに渡します。 テンプレートは content 変数を受け取れるようにしてください。

urlpatterns += patterns('',
    ...
    (r'^-0.96/(?P<doc>[0-9a-z-_\.]+)/$', render, dict(
        template_name = "doc/base.html",
    )),
)

ドキュメントテキストの場所を指定する

デフォルトでは app/docs 以下のテキストファイルを参照しますが、 任意のPATHを file_path_pattern に指定することができます。

urlpatterns += patterns('',
    ...
    (r'^-0.96/(?P<doc>[0-9a-z-_\.]+)/$', render, dict(
        file_path_pattern = (DIR % "branches/docs_0.96/%s") % PATHPATTERN,
    )),
)

file_path_pattern は文字列フォーマットの式に使用されます。 2つの文字列フォーマットコードを含む必要があります。

file_path_pattern = "../documentation/%s%s.txt"

1つ目のコードは app_name に相当します。 2つ目のコードは file_name に相当します。

文字コードを指定する

※開発中の機能です

ドキュメントテキストファイルの文字コードを指定する方法を紹介します。 HelpDoc は文字コードの解析をしません。 デフォルトは UTF-8 にセットされています。 その他の文字コードを使用する場合は urls.py で指定します。 指定されたエンコーディングでドキュメントテキストファイルが読み出されます。

urlpatterns += patterns('',
    ...
    (r'^-0.96/(?P<doc>[0-9a-z-_\.]+)/$', render, dict(
        encoding = "euc_jp",
    )),
)

ベースURLを変更する

※開発中の機能です

Django 管理画面 admin の配下になるようなURLで表示したい場合には myproject.helpdoc.urls が django.contrib.admin.urls よりも前にリストされるようにします。

urls.py

urlpatterns = patterns('',
    ...
    (r'^admin/mysite-help/', include('myproject.helpdoc.urls')),
    ...
    (r'^admin/', include('django.contrib.admin.urls')),
    ...
)

次に settings.HELPDOC_BASE_URL にベースパスを設定し、HelpDocコンテキストプロセッサを追加します。 これは admin/doc で表示されるドキュメントインデクスのテンプレートを書き換えるために必要です。

settings.py

HELPDOC_BASE_URL  = "/admin/mysite-help/"

TEMPLATE_CONTEXT_PROCESSORS = global_settings.TEMPLATE_CONTEXT_PROCESSORS + (
    "myproject.helpdoc.context_processors.helpdoc",
)

admin/doc で表示されるドキュメントインデクスのテンプレートを書き換える必要がない場合は urlpatterns に base_url 引数を与えるだけでも、うまく動作します。

urls.py

urlpatterns = patterns('',
    ...
    (r'^admin/mysite-help/', include('myproject.helpdoc.urls'), dict(
        base_url = "/admin/mysite-help/",
    )),
    ...
)

views.render

HelpDoc アプリケーションのレンダラーを単独で使用する方法を紹介します。 ちょうど Django に搭載されている Generic views のような感覚でアプリに埋め込むことができます。

urls.py

from django.conf.urls.defaults import *
from django.views.decorators.cache import cache_page
from helpdoc.views import render

render = cache_page(render, 24*60*60)

urlpatterns = patterns("",
    (r'^/(?P<doc>[0-9a-z-_\.]+)/$', render, dict(
        template_name = "doc/base.html",
        file_path_pattern = "../documentation/trunk/%s%s.txt"
    )),
    (r'^-0.96/(?P<doc>[0-9a-z-_\.]+)/$', render, dict(
        template_name = "doc/base.html",
        file_path_pattern = "../documentation/docs_0.96/%s%s.txt"
        encoding = "euc_jp",
    )),
)

docutilsの処理は重いので、Django に付属している CacheMiddleware で パフォーマンスを稼ぐことができます。 上の例では helpdoc.views.render に 24時間キャッシュするように設定しています。

Sitemap

ドキュメントテキストから sitemap.xml を生成する方法を紹介します。

urls.py

from django.conf.urls.defaults import *
from helpdoc.util import HelpdocSitemap

class DocJaSitemap(HelpdocSitemap):
    info_dict = dict(
        changefreq = "weekly",
        priority = 0.7,
    )
    target_dir = "../documentation/trunk/%s%s.txt"
    location = "/django/doc-ja/%s/"

sitemaps = {
    "doc-ja": DocJaSitemap(),
}

urlpatterns = patterns('',
    (r'^sitemap.xml$', 'django.contrib.sitemaps.views.sitemap',{'sitemaps': sitemaps}),
)

helpdoc.util.HelpdocSitemap を継承した Sitemapクラスを定義します。 デフォルト値は、 changefreq = "weekly", priority = 0.6, になっています。 更新時刻は、ファイルシステムの更新時刻を参照しています。

静的ファイルの配信

執筆中です。