Plone 開発者マニュアルを Plone CMS にアップロードする方法¶
説明
ここでは Sphinx と Plone の統合について説明しています。 また、例として Plone 開発者マニュアルと plone.org サイトを使用します。
はじめに¶
この文書は以下のような人を対象としています。
- Plone 開発者マニュアルの HTML バージョンを生成したい
- Sphinx で生成したドキュメントを Plone サイトにアップロードしたい
collective.developermanual とは¶
collective.developermanual は Sphinx フォーマットで記述された Plone 開発者のための誰でも編集できる文書です。
Sphinx は賢くて美しい文書ファイルを簡単に作成できるツールです。 Sphinx は Georg Brandl さんが作成し、BSD ライセンスの元に提供されています。
collective.developermanual は buildout.cfg のレシピ を含んでいます。
- Sphinx のインストール
- マニュアルをコンパイルして HTML を生成
- Plone サイトにマニュアルをアップロード (bin/topone スクリプトと transmogrify パッケージを使用)
Plone サイトが Sphinx の文書をアップロードできるようにするために特別な設定は必要ありません (Plone Help Center のインストールする以外に、 フォルダーとページを Reference Manual コンテントタイプの代わりに使用するようにパイプラインを定義することもできます)。
文書を作成とアップロードに必要なソフトウェアを設定する¶
最初に Git をあなたの OS にインストールして、ソースコードをチェックアウトできるようにする必要があります。:
sudo apt-get install git-core # Linux
or:
sudo port install git-core # Mac
Mac では以下のコマンドを実行します。:
sudo port install git-core # Mac
ノート
(訳注)この日本語化されたマニュアルのソースコードは Mercurial で管理されています。 そのため、ソースコードをチェックアウトするには Mercurial や TortoiseHg をインストールする必要があります。
ノート
Python 環境 (easy_install) に Sphinx をインストールしてはいけません。 buildout で作成したバージョンと衝突する可能性があるので削除してください。 他のプロジェクトで Sphinx が必要な場合は virtualenv を使用してください。
buildout を実行し Sphinx と関連するパッケージをインストールします。:
# ノート: Python 2.4 を使用してください
python2.4 bootstrap.py
bin/buildout
このコマンドの実行結果は常にエラーになりますが、 bin/ ディレクトリに必要なスクリプトが作成されています。 次に、Mr. Developer ツールを使用してすべてのソースコードをチェックアウトします。:
bin/develop co ""
再度 buildout を実行します。:
bin/buildout
Sphinx で静的な HTML を生成する¶
以下のコマンドを実行すると、buildout でインストールされた sphinx-build コマンドを使用して、 source ディレクトリにある collective.developermanual の全ページをコンパイルした静的 HTML が doc/html ディレクトリに生成されます。:
make html
全ての警告メッセージを見るためなど、最初からすべてを生成しなおしたい場合は以下のコマンドを実行します。:
make clean html
サイトに文書をアップロードする¶
collective.developer は Sphinx で生成した HTML ファイルを Plone サイトの Plone Help Center にリファレンスマニュアルとしてアップロードするための、 collective.transmogrify 用のパイプライン定義が buildout に含まれています。
collective.transmogrify はコンテンツをインポート/エクスポートするときのパイプライン(操作)を提供するために開発されました。 プラグイン機能を使用して必要な複数の手順(blueprints)を設定して、複数のパイプラインを連携することができます。 この考え方はビデオや音声ファイルのコーデックの考え方に非常に良く似ています。
blueprints は pipeline.cfg 設定ファイルを使用して、コンテンツを適合させます。 collective.developermanual は Sphinx で生成された HTML ファイルを走査し、 HTML をフィールド(タイトル、説明、本文)に分割して Plone サイトに Zope の XML-RPC と URL 機能を使用してアップロードする処理をパイプラインに定義しています。 Zope では XML-RPC 機能が必要となります。アップローダーのための特別なコードは、 Plone サイトが動作しているサーバーでは必要ではありません。
Sphinx の文書を Plone サイトにアップロードするための設定¶
最初に Plone Help Center アドオンをインストールし、 Reference Manual コンテントタイプをサイトに作成します。
文書をアップロードするためには以下の環境が必要です。
- Plone サイト
- Plone Help Center アドオン がインストールされている
- ソースコード、警告、ノートやその他の文書のマークアップにに色をつけるために、Sphinx 特有の CSS ファイルをインストールします(オプション)。 最も簡単な方法は、 sphinx.css ファイルを portal_skins レイヤーに手で追加することです。
アップロードの実行¶
buildout は bin/toplone スクリプトを生成します。
例として、以下のようなコマンドでローカルの Plone インスタンスに文書をアップロードします。
make clean html bin/toplone http://admin:admin@localhost:5011/foobar/knowledge-base/test/
アップロードスクリプトは以下のことを実行します。
- buildout を実行して生成します。(builtou.cfg を参照)
- コマンドラインから HTTP ベーシック認証を実行し、リモートサイトへ接続するための transmogrifier のパイプラインを再構成します。
- Sphinx 文書を走査してタイトル、説明と本文を抜き出します。 理論的にはここでリモートの Web サイトを走査することが可能です。 toplone スクリプトはローカルの文書のみを走査します。
- Zope の XML-RPC を使用して、リモートの Plone インスタンスに Plone Help Center コンテンツを作成します。
- Zope の XML-RPC を使用して、変更された文書をリモートの Plone のアイテムに反映します。
- 文書アイテムを公開し、不要なアイテム(画像やソースのフォルダ)を非表示にします。
ノート
現時点では、アップロードスクリプトはすでに存在する文書を削除しません。 ページの名前を変更したり削除した場合は、アップロードを実行する前に対象となる文書を削除する必要があります。 Reference Manual のコンテントタブを選択して、全ての文書を選択して削除します。
CSS の設定¶
例として sphinx.css は collective.developermanual に以下を提供します。
- It sets up CSS for default Sphinx styles (notices, warning, other adminition)
- シンタックス・ハイライティングのための CSS を設定します。
- Sphinx と plone.org のテーマの間で衝突している CSS のクラスを解決します。
sphinx.css は Sphinx の特別なテンプレート page.html で使用されていると仮定しています。 このテンプレートは Spinx が出力する全ての sphinx-content CSS クラスを変更します。そうすることにより、標準の Plone のスタイルときれいに分離することができています。
page.html は sources/_templates/page.html にあります。
