Outdated version of the documentation. Find the latest one here.

ドキュメント作成のガイドライン

はじめに

QGISドキュメントはPDT(太平洋夏時間)0時、午前8時、午後4時に、サーバー上で自動的に構築されます。現在の状況はhttp://docs.qgis.orgで入手可能です。

QGISドキュメントは、HTML出力を後処理するスフィンクスツールセットからいくつかのスクリプトと相まって、主にreStructuredTextの(reST) 形式の構文を使用して書かれています。http://docutils.sourceforge.net/docs/ref/rst/restructuredtext.htmlまたはhttp://sphinx.pocoo.org/markup/inline.htmlを参照してください。

QGISプロジェクトの最初の文書を作成する際に一般的には、 `Pythonのドキュメントのスタイルガイドライン<http://docs.python.org/devguide/documenting.html> ` _に従ってください。以下では、QGISのドキュメントを書くためにreSTを使用する際に従うべきいくつかの一般的なガイドラインを公開しています。

QGISプロジェクトに貢献したりリポジトリを管理する上での一般的な規則をお探しであれば、`QGISコミュニティーに関わる<http://qgis.org/en/site/getinvolved/index.html> ` _に助けが見つかります。

ドキュメントを書く

見出し

ドキュメントの各ウェブページに `` .rst``ファイルが対応しています。

テキストを構造化するために使用されるセクションはそれらのタイトルを通じて同定されます。タイトルには下線(及び第1レベルに対して上線)が引かれます。同じレベルのタイトルは下線装飾のために同じ文字を使用する必要があります。QGISドキュメントでは、章、セクション、サブセクションとminisecに対して以下のスタイルを使用する必要があります。

********
Chapter
********

Section
=======

Subsection
----------

Minisec
.......

Subminisec
^^^^^^^^^^

行内タグ

いくつかの項目を強調するために、テキスト内のいくつかのタグを使用できます。

  • メニューGUI:サブメニューを選択し、特定の操作、またはこのような配列のいずれかのサブシーケンスを選択するなど、メニュー選択、の完全な配列をマークします。

    :menuselection:`menu --> submenu`
  • ダイアログおよびタブのタイトル:ラベルは、ウィンドウのタイトル、タブのタイトルとオプションのラベルを含むインタラクティブなユーザインターフェースの一部として提示しました。

    :guilabel:`title`
  • ボタンのラベル

    **[Apply]**
  • ファイル名またはディレクトリ

    :file:`README.rst`
  • アイコンに属するポップアップテキストを持つアイコン

    |icon| :sup:`popup_text`

    ( 以下の`image`_を参照してください)。

  • ショートカットキーボード

    :kbd:`ctrl B`

    :kbd:`CtrlキーB`と表示されます

  • ユーザーテキスト

    ``label``
    

ラベル/参照

テキスト内にアンカーを配置するために参照が使用されます。セクションやページ間のハイパーリンクを作成し呼び出しできます。

以下の例は、セクション(例えば、ラベル/参照タイトル)のアンカーを作成します

.. _my_anchor:

Label/reference
---------------

**同じページ**中の参照を呼び出すために使用するのは

see my_anchor_ for more information.

これが返すのは:

詳細についてはmy_anchor_を参照してください。

それはアンカー ‘は次の次の行/事にジャンプします注意してください。通常、このラベルを宣言するために、アポストロフィを使用する必要はありませんが、アンカーの前後に空行を使用する必要があります。

文書内のどこからでも 同じ場所にジャンプする別の方法は、:ref: 役割を使用することです。

see :ref:`my_anchor` for more information.

その代わりに、キャプションが表示されます(この場合は、このセクションのタイトルを!):

詳細については ラベル/参照 を参照。

だから参照1(my_anchor)と参照2(ラベル/参照)。参照は多くの場合キャプションを完全に表示しているので、語*セクション* を使用する必要は本当はありません。参照を記述するためにカスタムのキャプションも使用できます

see :ref:`Label and reference <my_anchor>` for more information.

返します:

詳細については :ref:`ラベルや参照<my_anchor> ` を参照。

図形及び画像

ピクチャー

画像を挿入するには、使用します

.. image:: /static/common/qgislogo.png
   :width: 10 em

これを返します

../../_images/qgislogo.png

置換

テキスト内の画像を置くか、どこにでも使用するエイリアスを追加できます。段落内の画像を使用するには、どこかのエイリアスを作成します。

.. |nice_logo| image:: /static/common/qgislogo.png
               :width: 2 em

そして、あなたの段落でそれを呼び出します:

my paragraph begins here with a nice logo |nice_logo|.

ここでは、この例になる方法です。

私の段落は、ここで素敵なロゴ|nice_logo|から始まります。

ノート

現在、QGISのアイコンを使用することに一貫性と支援を確保するために、エイリアスのリストが 置き換え 章の中で構築され使用可能です。

.. _figure_readme_1:

.. only:: html

   **Figure Readme 1:**

.. figure:: /static/common/qgislogo.png
   :width: 20 em
   :align: center

   A caption: A logo I like

結果は以下のようになります。

Figure Readme 1:

../../_images/qgislogo.png

キャプション:私の好きなロゴ

HTMLファイルだけで見える図(**図のReadme 1 **)に番号を作成するには、``.. only:: html``を使用します。スクリプトによって、PDFの図のキャプションの前に自動的に生成された番号が挿入されます。

キャプションを使用するには、図形ブロック内の空白行の後にインデントテキストを挿入するだけです(私のキャプションを参照してください)。

図への参照は、このような参照ラベルを使用して実現できます

(see Figure_Readme_1_).

これは、アンカーFigure_Readme_1_が表示されます。大文字を使用したければ使用できます。同じ .rst 文書では使用できますが、その他の.rstの文書ではできません。

もはや参照のための ``:ref:``役割を使用できません、HTMLのキャプションへの参照が失われているので(それは今は 図Readme 1: の前の場所を参照する)

see :ref:`figure_readme_1`, does not work due to the lost reference to
the caption of the figure, this is not a 'bug' but a choice we made!

テーブル

簡単な表を作成するには

=======  =======  =======
x        y        z
=======  =======  =======
1        2        3
2        4
=======  =======  =======

空きスペースを残すためには、空きスペースの前に```` を使用してください。

彼らは参照を使用し、すべての描画することで、より複雑なテーブルも使用できます

.. _my_drawn_table_1:

+---------------+--------------------+
| Windows       | Mac OSX            |
+---------------+--------------------+
| |win|         | |osx|              |
+---------------+--------------------+
| and of course not to forget |nix|  |
+------------------------------------+

My drawn table, mind you this is unfortunately not regarded a caption

You can reference to it like this my_drawn_table_1_.

結果:

ウィンドウズ

MacOSX

win osx

そしてもちろん nix を忘れないように

私の描かれたテーブル、これは残念ながらキャプションを考えていない心

それはこのようにmy_drawn_table_1_で参照できます。

インデックス

いくつかのインデックスタグは、RSTに存在します。インデックスを翻訳できるようにするには、通常のテキストに統合する必要があります。この場合、次の構文を使用します。

QGIS allows to load several :index:`Vector formats` supported by GDAL/OGR ...

語を翻訳する必要がない場合は、この構文を使用してください:

.. index:: WMS, WFS, WCS, CAT, SFS, GML, ...

脚注

ご注意:脚注は翻訳ソフトでは認識されず、またPDF形式に適切に変換されません。だから、可能であればドキュメント内では脚注は使用しないでください。

これは、脚注を作成するためのものです

blabla [1]_

どちらを指しています:

[1]

コアプラグインのアップデート

スクリーンショットを管理する

新しいスクリーンショットを追加

ここでは、新たな、見栄えの良いスクリーンショットを作成するためのいくつかのヒントです。ファイル:ユーザーガイドについて、彼らが入る。 /リソース/ EN / user_manual /

  • すべての画面のキャップのための同じ環境(同じOS、同じ装飾、同じフォントサイズ)。私たちは、Unityとデフォルトの「雰囲気」をテーマとUbuntuのを使用しました。QGISのメインウィンドウとコンポーザのスクリーンショットのためには、ウィンドウ(ユニティではないデフォルト)のメニューを表示するように設定しています。

  • 機能を表示するために必要な最小限のスペースにウィンドウを縮小(小さなモーダルウィンドウのために、すべての画面を撮る>行き過ぎ)

  • ごちゃごちゃしていないほど良い(すべてのツールバーをアクティブにする必要はありません)

  • イメージエディタでそれらのサイズを変更していない、必要であれば、サイズは(適切に醜い解像度>を増額せずに寸法をダウンスケーリング)最初のファイルに設定されます。

  • 背景をカット

  • 例えばGimpの中に135 dpiの、に設定して印刷サイズ解像度は、印刷解像度(画像>印刷サイズ)を設定して保存します。何のサイズが最初のファイルに設定されていない場合は、この方法は、画像がHTMLにし、PDFでの良好な印刷解像度で元のサイズになります。画像のバッチを実行するためにコマンドを変換ImageMagickのを使用できます。

convert -units PixelsPerInch input.png -density 135 output.png
  • PNGに保存(JPEG損失なし)

  • スクリーンショットは、テキストに記載されているものによってコンテンツを表示する必要があります

  • /qgis-projects 中には、スクリーンショットを作成するために前に使用されていたいくつかの準備QGIS-プロジェクトを見つけることができます。このため、簡単にQGISの次のバージョンのスクリーンショットを再現できます。これらのプロジェクトは、QGIS `サンプルデータ<http://qgis.org/downloads/data/>`_ (別名アラスカデータセット) を使用し、QGIS-ドキュメントリポジトリと同じフォルダに配置する必要があります。

  • メニューの持つ小さなアプリケーション画面を作成するために、Ubuntuの中でグローバルメニューの機能を削除するには、次のコマンドを使用します。

sudo apt-get autoremove appmenu-gtk appmenu-gtk3 appmenu-qt

スクリーンショットを翻訳

ここには翻訳されたユーザーガイド用のスクリーンショットを作成するためのいくつかのヒントがあります。それらは ./resources/<your language>/user_manual/ になります

  • すべての画面のキャップのための同じ環境(同じOS、同じ装飾、同じフォントサイズ)

  • QGIS-ドキュメントリポジトリ( ./qgis_projects で)に含まれるQGIS-projectsを使用してください。これらは、マニュアルの「元」のスクリーンショットを生成するために使用されました。QGIS サンプルデータ<http://qgis.org/downloads/data/> _ (別名アラスカデータセット)は、QGIS-ドキュメントリポジトリと同じフォルダに配置する必要があります。

  • 英語のオリジナル “スクリーンショットと同じサイズです。そうでない場合は延伸され見栄えが悪くなるでしょう。長いUI文字列のために異なるサイズを持っている必要がある場合は、ご自身の言語のrstコードの寸法を変更することを忘れないでください。

  • 地物を表示するために必要な最小限のスペースにウィンドウを縮小(小さなモーダルウィンドウのために、すべての画面を撮る>行き過ぎ)

  • ごちゃごちゃしていないほど良い(すべてのツールバーをアクティブにする必要はありません)

  • 画像エディタでそれらのサイズを変更しないでください、サイズがrstファイルに設定されます(解像度を適切に増やさずに寸法をダウンスケーリング>醜い)。

  • 背景をカット

  • PNGに保存(JPEG損失なし)

  • スクリーンショットは、テキストに記載されているものによってコンテンツを表示する必要があります

処理アルゴリズムの文書化

アルゴリズムを処理するための文書をお書きになる場合は次のガイドラインを考慮してください。

  • 他の情報源(例えばQGISソースツリーや処理 - ヘルプリポジトリ)からファイルで、既存のヘルプファイルを上書きしない、このファイルには、異なるフォーマットを持っています

  • 処理アルゴリズムのヘルプファイルには、QGISユーザーガイドの一部であるので、ユーザガイドとその他のドキュメントと同じフォーマットを使用します

  • 「これはそのアルゴリズムはこれとそれを行う...」アルゴリズム記述の最初の文として使用を避けます。TauDEMまたはGRASS algoritmsヘルプのような、より一般的な言葉を使用してみてください

  • 必要に応じて画像を追加します。PNG形式を使用して文書化のための一般的なガイドラインに従ってください。

  • 必要ならば「も参照してください」セクションに追加情報へのリンク(例えば出版物やウェブページ)を追加します

  • (再びGRASSとTauDEMが良い例です)アルゴリズムパラメータおよび出力のための明確な説明を与えます。

  • パラメータまたは出力名は編集しないでください。タイプミスや間違ったスペルを見つけられた場合は、開発者が処理コードでも修正できるように、bugrackerでご報告ください

  • アルゴリズム記述、すでにパラメータの説明に記載されているオプションで利用可能なオプションの一覧を表示しません。

  • パラメータの説明ではすでに利用可能な情報として、説得力のある理由なしに、アルゴリズムやパラメータの説明に情報ベクトルジオメトリタイプを追加しないでください