この文書を書いて更新するには¶
説明
Plone 開発者マニュアルの書き方とテキストの提出方法
貢献者を募集中¶
以下のような文書と外部文書を参照するための情報が求められています。
- 新しいコードスニペット(短いサンプルコード)とシステムの説明
- 外部の資料へのリンク
- コンポーネントの README へのリンク
- 特定の課題についてのブログのエントリーへのリンク
- メーリングリストの議論へのリンク
- ソースコードへのリンク (バージョンコントロールシステムへの直接リンク)
貢献する方法¶
plone collective のバージョン管理システムに直接コミットする¶
この方法がおすすめです。コミットを実行することを躊躇しないでください。 もしあなたが文書を破壊したり誤った情報を書き込んだとしても、すぐにまたは後で元に戻すことが可能です。 それに誰もあなたを攻めたりはしません、人に起因したエラーは常に発生するものです。
Sphinx と restructured text について学んで下さい。 (訳注: Sphinx (日本語版) と reStructuredText入門 (日本語版) があります。)
文書のソースファイルを取得します:
svn co https://svn.plone.org/svn/collective/collective.developermanual/trunk collective.developermanual
あなたが更新したいファイルを編集します。
Sphinx で文書を構築して、警告が発生しないかを確認します。:
sphinx-build source build
変更をコミットします。:
svn commit -m "My message what I changed"
訳注: 日本語版の文書を変更したい場合は、以下のようにする必要があります。
Mercurial をインストールします。
bitbucket.org にアカウントを登録します。
作成したアカウントで bitbucket にログインし、 collective.developermanual-ja をフォローします。のちほどリポジトリへの書き込み権限を設定します。
文書のソースファイルを取得します:
hg clone http://bitbucket.org/takanori/collective.developermanual-ja
あなたが更新したいファイルを編集します。
Sphinx で文書を構築して、警告が発生しないかを確認します。:
sphinx-build source build
変更をコミットします。:
hg commit -m "My message what I changed"
変更をサーバーに反映させます。:
hg push
変更依頼を誰に依頼するべきか¶
あなたが subversion や reST フォーマット文書の編集についての技術的なスキルを持っていない場合は、以下のアドレスにメールで提案してください。
- mikko.ohtamaa (at) mfabrik (dot) com
ノート
その提案は文書に直接入れられるような形でのテキストである必要があります。 あなたの依頼に対して、ボランティアで書き方を教えてくれる人はあまりいません。
ノート
訳注: この日本語版については takanori (at) takanory (dot) net にメールで連絡ください。
文書のフォーマット¶
ここでは文書をどのように書くべきかのいくつかのルールを記載しています。
ページの構成¶
それぞれのページは以下の情報を必ず順番で記載します。
表題: ここに記載された内容は目次に表示されます。:
====================================
この文書を書いて更新するには
====================================
ページの説明は plone の Dublin Core メタデータフィールド 説明 のようなもので、reST の admonition ディレクティブを使用して記述します。 Google などの検索エンジンの結果に表示される文章と同じように、一つのパラグラフ(空行をいれない)で1〜3行で記述することをおすすめします。:
.. admonition:: Description
このテキストは plone のページの説明フィールドとなります。
このページを検索エンジンがリスティングするときに使用します。
contents ディレクティブによって Sphinx はページの最初に各見出しへのリンクを生成します。 local オプションを指定することにより目次のタイトルを表示しません。:
.. contents :: :local:
「はじめに」の節: このページが何についての文書なのかを説明します。:
はじめに
------------
この章ではこの文書に対しての貢献の基本的なことがらについて説明します。
いくつかの節: 文書の実際の内容を記述します。:
貢献者を募集中
--------------------
以下のような文書と外部文書を参照するための情報が求められています。
シンタックスハイライティング¶
Sphinx はシンタックスハイライティングに Pygments ライブラリを使用しています。
以下のようプログラムのコードに対して、異なったハイライティング(色付け)を指定することができます。
二つのコロン(:)を記述するとデフォルトのハイライティングを使用してコードを表示します。::
# Some Python code here
# The language defaults to Python, we don't need to set it
if 1 == 2:
pass
code-block を使用するとハイライティングする言語を指定できます。:
.. code-block:: python
if "foo" == "bar":
# This is Python code
pass
XML の場合は以下のように指定します。:
.. code-block:: xml
<somesnippet>Some XML</somesnippet>
UNIX シェルの場合は以下のように指定します。:
.. code-block:: console
# A comment
sh myscript.sh
ハイライティングのモードを文書全体に対して設定します。:
.. highlight\:\: console
All code blocks in this doc use console highlighting by default::
some shell commands
シンタックスハイライティングは有効になっていない場合は、指定した構文にエラーがあり Pygments が失敗していますがエラーは出力されません。
他の Sphinx と restructured text のコードの例¶
イタリック:
この *単語* はイタリックで表示されます。
強調:
この **単語** は太字で表示されます。
インラインのコードハイライティング:
これは ``aFunction()`` です。
外部へのリンクの作成 (アンダースコアを最後につけます):
`これは外部へのリンクの例です <http://mfabrik.com>`_
内部へのリンクの作成:
:doc:`これは内部へのリンクの例です </introduction/writing.txt>`
箇条書き:
* 最初の項目
* 二つ目の項目と `リンク <http://mfabrik.com>`_
情報ボックス¶
以下にこの文書全体で使用できるいくつかの情報ボックスについて説明します。 Sphinx の warning (警告) と note (備考) ディレクティブを使用します。
セキュリティ上の警告¶
警告
セキュリティ: この情報ボックスは plone のセキュリティ上の仕組みに依存するかもしれない場合に使用します。 これはログインしたユーザの種類や、どのような手順でその機能を実行したかによって、結果が異なるということを意味しています。
例:
警告
セキュリティ: invokeFactory() はログインしたユーザがコンテンツを作成する権限があるかを確認します。
