docgen.py: Kid + XHTML = static file goodness

turbogears.docgen モジュールはTurboGearsサイトの静的な部分を生成することに対応しています。

TurboGears?のドキュメントは、すべての人に理解ができウェブによく適しているのでXHTMLで書かれています。XHTMLを使うことによってJavaScriptによるシンタクスハイライトのようなこともできます。

このドキュメントは、 py:match ルールを通してサイト全体にスタイルを適用したKidテンプレートです。一般的に言えばthere's not much else that's special about it. The main trick is that if you're writing about Kid, you'll need to use two $ symbols whenever you want to show off ${} variable interpolation.

新しいドキュメントファイルの基本的な部分は newdocs/newfile.html にあります。これはメインのコンテンツテンプレートを拡張します。

（画像やCSS、JavaScriptなどの）他の静的なファイルはすべてそのまま最終的なサイトへコピーされるでしょう。サイトを構築するときには、docgenはオリジナルディレクトリのミラーを生成しますので、もしファイルを削除するとサイトからも削除されるでしょう。

印刷できるドキュメント

dogenは（未完成ながら） "印刷可能な" ドキュメントのバージョンを生成する能力を持っています。印刷可能なドキュメントはすべてのナビゲーション要素が削除されたテンプレートを持っています。同等のことはCSSを利用しても可能ですが、これ以外にもdocgenには、複数ページを一つにまとめることができるという機能もあります。 "20 Minute Wiki" チュートリアルは元々この機能のために作られたものでした。このチュートリアルは６つのページに分かれていますが、印刷時には単一ページの形であることが望まれます。ですので、TurboGearsドキュメントは標準的なXMLを使ったXHTMLとなっているのであり、このことが複数ファイルを一つのファイルに結合され、ステキな出力ができる印刷可能なテンプレートを適用することを可能にしているのです。

印刷可能なドキュメントのジェネレータはすべてのドキュメントに適用されるわけではありません。そういう場合にはCSSがよい解決法となるでしょう。また、このジェネレータはオリジナルファイルの変更を全くチェックしません。ただ生成するだけなのです。Finally, it's not really written in a convenient, generic way to easily apply it to additional files.

あなたのマシンでサイトを構築する

最終的にレンダリングされたドキュメントがどの様に見えるのかを知りたいのなら、以下のコマンドを実行することで簡単にそれを行うことができます:

python setup.py localsite

このコマンドは dist/docs にサイトのコピーを生成します。ただし大きいビデオファイルやダウンロードのためのeggファイルはここには含まれません。これらのファイルは実際にサイトを構築するのとは別々にコピーされます。