Make組ブログ

Python、Webアプリや製品・サービス開発についてhirokikyが書きます。

Django製サイトにSphinx製ドキュメントを導入する方法

Django Sphinx

Django製のサイトにSphinx製のドキュメントをアッサリ導入する方法。
Sphinxドキュメントを

http://example.com/docs/

に導入できる。
ユーザーグループのサイト作って、ドキュメントを/docs/以下に用意したい人とかが対象になると思う。

記事の内容はほとんどdjango-sphinxdocの導入方法。
これを使えばアッサリ解決できる。

環境

それぞれ pip とかでインストール。

sphinxdocの設定

基本的にはdjango-sphinxdocのドキュメントを参考に

urls.pyに

   url(r'^docs/', include('sphinxdoc.urls')),

を追加。

settings.pyのINSTALL_APPSに

   'sphinxdoc'

を追加。

haystackの設定

django-haystackはサイト内検索に使う。
Solr、 Elasticsearch、 Whoosh、Xapianとかいうのに対応している。
今回は内部に、Python製の全文検索ライブラリWhooshを使う。

基本的にはdjango-haystackのドキュメントを参考に

※このドキュメント読むときはhaystackのバージョンに気をつけて。

settings.pyのINSTALL_APPSに

'haystack'

を追加。

settings.pyに

HAYSTACK_SITECONF = 'myproject.search_sites'
HAYSTACK_SEARCH_ENGINE = 'whoosh'
HAYSTACK_WHOOSH_PATH = '/path/to/whooshindexes'

を追加。'myproject.search_sites'、'/path/to/whooshindexes'は適宜編集。

myproject/search_sites/__init__.pyに

import haystack
haystack.autodiscover()

を追加。

ドキュメントのビルド

データベースの同期。

% python manage.py syncdb

そして走らせる。

% python manage.py runserver

管理画面を開くとSphinxdocアプリにProjectというモデルがある。
これに導入したいドキュメントに関する情報を入力すると、/docs/以下にドキュメントが追加されるという仕組み。

管理画面からProjectモデルを追加する。

  • Name: ドキュメントの名前
  • Slug: URLに使うドキュメントの名前。Nameと同じで良い。
  • Path: ドキュメントのディレクトリ(conf.pyがあるところ)へのパス。

あとは

$ python manage.py updatedoc -b <project-slug>

でビルドできる。は管理画面から与えたProjectモデルのSlugの値。
(ビルドされたドキュメントはsphinxdocアプリのdocumentモデルに保存される)

base.htmlを用意する

おもむろに /docs/ にアクセスしてみると

TemplateDoesNotExist at /docs/
base.html

と、「base.htmlが無い」というエラーがでる。

templatesとかディレクトリ作ってbase.htmlを配下に追加。
settingsのTEMPLATE_DIRSにtemplatesを追加すれば良い。


そしたらちゃんとブラウザからビルドされたドキュメントが見れるはず。
例としてDjangoの日本語ドキュメントをビルドしてみた

base.htmlはテキトーにこんなかんじ

<html>
<head>
<title>
{% block title %}{% endblock %}
</title>
<head>
<body>
{% block content %}
{% endblock content %}

{% block sidebar %}
{% endblock sidebar %}
</body>
</html>

とりあえずできる。

おわりに

あとはhaystackの設定とかbase.htmlを各々の環境に合わせれば良い。

ただbase.htmlをsphinxdocのインストール先に追加してるが気に入らない。良い方法模索したい。