ガイドラインを書く

In general, when creating reST documentation for the QGIS project, please follow the Python documentation style guidelines. For convenience, we provide a set of general rules we rely on for writing QGIS documentation below.

文書を書く

見出し

文書の各ウェブページに .rst ファイルが対応しています。

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

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

Section
=======

Subsection
----------

Minisec
.......

Subminisec
^^^^^^^^^^

Lists

リストはテキストを構造化するのに役立ちます。こちらはすべてのリストに共通な簡単な規則のいくつかです：

• すべての項目を大文字で始めてください

• 単一の単文のみを含むリスト項目の後に句読点を使用しないでください

• 複数の文または1つの複合文からなるリスト項目の句読点としてピリオド（ . ）を使用します

行内タグ

テキスト内では項目を強調するためにタグを使用できます。

• メニューGUI ：サブメニューを選択したり、特定の操作、またはこのような配列の何らかの部分配列を選択するなど、メニュー選択の完全な配列をマークします。

  :menuselection:`menu --> submenu`
  

• ダイアログおよびタブのタイトル ：ウィンドウのタイトル、タブのタイトル、ボタンやオプションのラベルなど、対話的なユーザーインターフェイスの一部として提示されるラベル。

  :guilabel:`title`
  

• ファイル名またはディレクトリ

  :file:`README.rst`
  

• アイコンに属するポップアップテキストを持つアイコン

  |icon| :sup:`popup_text`
  

  （ 以下の 画像 を参照してください）。

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

  :kbd:`Ctrl+B`
  

  will show Ctrl+B

  キーボードショートカットを説明するときは、次の規則を使用してください：

  • Letter keys are displayed using uppercase: S

  • Special keys are displayed with an uppercase first letter: Esc

  • キーの組み合わせはキー同士の間に空白を入れずに + 記号を表示し、 Shift+R のように表示します。

• ユーザーテキスト

  ``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.

返します：

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

Figures and Images

ピクチャ

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

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

これを返します

置換

テキスト内には画像を置くか、どこでも使用される別名を追加できます。段落内で画像を使用するには、 最初に source/substitutions.txt ファイル中に別名を作成します：

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

and then call it in your paragraph:

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

This is how the example will be displayed:

My paragraph begins here with a nice logo .

HTMLレンダリングに最も近いドキュメントのプレビューをGitHubでレンダリングするには、変更したファイルの末尾に画像置換呼び出しを追加する必要もあります。これは substitutions.txt からコピーペーストするか、 scripts/find_set_subst.py スクリプトを実行することで行えます。

注釈

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

図

.. _figure_logo:

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

   A caption: A logo I like

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

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

他の参照との競合を避けるために、図はつねに _figure_ でアンカーしてください。図のキャプションを簡単に参照できる用語を使用することをお勧めします。画像には中央揃えの位置揃えのみが必須ですが、必要に応じて図の他のオプション（ width 、 height 、 scale など）を自由に使用してください。

スクリプトにより、作成されたPDF版の文書の図のキャプションの前に自動作成された番号が挿入されます。

キャプションを使用するには（ My caption を参照）、図ブロックに空白行の後ろに字下げテキストを挿入します。

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

(see Figure_logo_).

それはアンカー Figure_logo を表示します。大文字を使用することもできます。これは同じ .rst 文書では使用できますが、他の文書では使用できません。他のファイルからの参照のために :ref: の役割を引き続き使用できますが、これは画像の完全なキャプションを返すことに注意してください。

see :ref:`figure_logo`

返します：

キャプション：私の好きなロゴ 参照

テーブル

簡単な表を作成するには

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

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

より複雑な表も、参照およびすべてを使用すると作成できます。

.. _my_drawn_table:

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

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

You can reference to it like this my_drawn_table_.

結果：

ウィンドウズ	macOS
そしてもちろん を忘れないように

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

my_drawn_table のように参照できます。

索引

索引は、読者が文書内の情報を簡単に見つけるのを助ける便利な方法です。 QGISの文書作成では、いくつかの重要な索引があります。本当に有用な（一貫性があり、整合性があり、本当に互いに関連付けされている）索引のセットを保持するための規則はほとんどありません。

• 索引は、人間が読めるもの、理解できるもの、翻訳可能なものでなければなりません。索引は複数の単語から作ることができますが、 loading_layers や loadingLayers の代わりに Loading layers というように、それらを繋ぐ不要な _ 、 - 、・・・は使用しないようにしてください。

• 単語に特殊なスペルがない限り、索引の最初の文字のみを常に大文字にします。その場合は、 Loading layers　レイヤーを読み込む 、 Atlas generation　地図帳を作成 、 WMS、pgsql2shp などのスペルをそのまま使用します。 `

• もっとも便利な式を正しいスペルで再利用し、間違った重複を避けるために、既存の 索引一覧 に注目してください。

いくつかの索引タグがRSTにはあります。通常テキスト内で行内 :index: タグも使用できますし

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

あるいは、次の段落の先頭にリンクする index:: ブロックレベルのマークアップを使うこともできます。上記のルールのため、後者のタグを使用する方が簡単なので、このタグを使用することをお勧めします。

.. index:: WMS, WFS, Loading layers

索引のより構造化され、相互接続されたテーブルを構築するために、 single 、 pair 、 see ...などの索引パラメーターを使用することもお勧めします。索引作成の詳細については、 Index generating を参照してください。

特別のコメント

場合によっては、警告、思い出させる、またはユーザーにいくつかのヒントを与えるために、説明のいくつかの点を強調したい場合があります。 QGISドキュメントでは、 .. warning:: 、 ..note:: や ..tip:: などのreST特殊ディレクティブを使用して、コメントを強調する特定のフレームを生成します。詳細は 段落レベルのマークアップ を参照してください。警告とヒントの両方に明確で適切なタイトルが必要です。

.. tip:: **Always use a meaningful title for tips**

 Begin tips with a title that summarizes what it is about. This helps
 users to quickly overview the message you want to give them, and
 decide on its relevance.

Code Snippets

また、例を挙げてコードスニペットを挿入することもできます。この場合、 :: ディレクティブを挿入した行の下にコメントを書いてください。ただし、レンダリングを改善するため、特に言語に応じてコードに色のハイライトを適用するには、code-blockディレクティブ、例えば .. code-block:: xml を使用してください。詳細は コードを表示する で。

注釈

注記、ヒントフレーム、および警告フレームのテキストは翻訳可能ですが、コードブロックフレームは翻訳を許可しないことに注意してください。したがって、コードサンプルに関連しないコメントは避け、必要なだけ短くしておいてください。

脚注

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

これは、脚注を作成するためのものです（例として示します 1 ）

blabla [1]_

これが指しているのは：

1

コアプラグインの更新

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

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

Here are some hints to create new, nice looking screenshots. The images should be placed in a img/ folder, in the same folder as the referencing .rst file.

• You can find some prepared QGIS-projects that are used to create screenshots in the ./qgis-projects folder of this repository. This makes it easier to reproduce screenshots for the next version of QGIS. These projects use the QGIS Sample Data (aka Alaska Dataset), which should be placed in the same folder as the QGIS-Documentation Repository.

• Reduce the window to the minimal space needed to show the feature (taking the whole screen for a small modal window > overkill)

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

• Don't resize them in an image editor; the size will be set into the .rst files if necessary (downscaling the dimensions without properly upping the resolution > ugly)

• 背景はカットします

• 背景が白でない場合は上部の角を透明にします

• Set print size resolution to 135 dpi (e.g. in Gimp set the print resolution Image ‣ Print size and save). This way, images will be at original size in html and at a good print resolution in the PDF. You can also use ImageMagick convert command to do a batch of images:

  convert -units PixelsPerInch input.png -density 135 output.png
  

• Save them in .png (no .jpeg artifacts)

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

ちなみに

If you are on Ubuntu, you can use the following command to remove the global menu function and create smaller application screens with menus:

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

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

Here are some hints to create screenshots for your translated user guide. Translated images should be placed in a img/<your_language>/ folder, in the same folder as the referencing .rst file.

• QGIS文書作成リポジトリ（ ./qgis_projects 中）に含まれるQGISプロジェクトを使用してください。これらは、マニュアルの「元」のスクリーンショットを生成するために使用されました。QGIS サンプルデータ （別名アラスカデータセット）は、QGIS-ドキュメントリポジトリと同じフォルダに配置する必要があります。

• 英語の「元の」スクリーンショットと同じファイル名で

• Reduce the window to the minimal space needed to show the feature (taking the whole screen for a small modal window > overkill)

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

• Don't resize them in an image editor; the size will be set into the .rst files if necessary (downscaling the dimensions without properly upping the resolution > ugly)

• 背景はカットします

• Save them in .png (no .jpeg artifacts)

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

プロセッシングアルゴリズムの文書を作成する

プロセッシングアルゴリズムのための文書をお書きになる場合は以下のガイドラインを考慮してください：

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

• 各アルゴリズムのドキュメントは対応する プロバイダ フォルダと グループ ファイル中に置いてください。アルゴリズム ボロノイポリゴン は QGIS プロバイダと vectorgeometry グループに属します。そのため、説明を追加する正しいファイルは source/docs/user_manual/processing_algs/qgis/vectorgeometry.rst です。

  注釈

  ガイドを書き始める前に、アルゴリズムがすでに説明されているかどうかを確認してください。この場合、既存の説明を拡張できます。

• 各アルゴリズムがプロバイダ名+アルゴリズム自体の一意の名前に対応する アンカー を持つことは非常に重要です。これにより、[ヘルプ]ボタンをクリックして[ヘルプ]ページを正しいセクションに開くことができます。アンカーはタイトルの 上 に配置する必要があります。 （ ラベル/参照 セクションも見てください）:

  .. _qgisvoronoipolygons:
  
  Voronoi polygons
  ----------------
  

  アルゴリズム名を調べるには、「プロセシング」ツールボックスのアルゴリズム上にマウスを置くだけです。

• アルゴリズムの説明の最初の文として、「このアルゴリズムではこれこれを実行しています...」を使用しないでください。以下のようなより一般的な表現を使ってみてください:

  Takes a point layer and generates a polygon layer containing the...
  

• アルゴリズムの名前を複製してアルゴリズムの動作を説明することは避け、パラメータの説明にパラメータの名前を複製しないでください。例えば、アルゴリズムが ボロノイポリゴン の場合、 入力レイヤ `` を ``ポリゴンを計算するレイヤ のように説明することを検討してください。

• 説明中ではアルゴリズムにQGISのデフォルトショートカットがあるか​​、またはインプレース編集をサポートするのかを示します。

• 画像を追加しましょう！絵は千の言葉に匹敵します！ .png フォーマットを使用し、ドキュメントの一般的なガイドラインに従ってください（詳細は 画像 セクションを参照）。画像ファイルは正しいフォルダ、つまり編集中の .rst ファイルの隣の img フォルダに置きます。

• 必要に応じて、アルゴリズムに関する追加情報（例：出版物やWebページ）を提供する「関連項目」セクションへのリンクを追加してください。実際に見るものがある場合にのみ、 "See also" セクションを追加してください。良い習慣として、 "See also" セクションは同様のアルゴリズムへのリンクで埋められます。

• アルゴリズムのパラメータと出力について明確に説明してください。既存のアルゴリズムからヒントを得てください。

• アルゴリズムオプションの詳細な説明と重複しないようにしてください。これらの情報はパラメータの説明に追加してください。

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

• Add the default value of the parameter in italic, e.g.:

  ``Number of points`` [number]
    Number of points to create
  
    Default: *1*
  

• サポートされている入力の タイプ を説明してください。１つを選べる利用できるタイプはいくつかあります：

  Parameter/Output type	Description	Visual indicator
  Point vector layer	vector: point
  Line vector layer	vector: line
  Polygon vector layer	vector: polygon
  Generic vector layer	vector: any
  Vector field numeric	tablefield: numeric
  Vector field string	tablefield: string
  Vector field generic	tablefield: any
  Raster layer	raster
  Raster band	raster band
  HTML file	HTML
  Table layer	table
  Expression	expression
  Point geometry	coordinates
  Extent	extent
  CRS	crs
  Enumeration	enumeration
  List	list
  Number	number
  String	string
  Boolean	boolean
  Folder path	フォルダ

• 最善の選択肢は、良い文書化がされている既存のアルゴリズムを研究し、すべての有用なレイアウトをコピーすることです。

• アルゴリズムが出力を提供しない場合は、そのセクションを飛ばしてください。

• 終了したら 一歩ずつの貢献 に書かれているガイドラインに従って変更をコミットしプルリクエストを行ってください。

こちらがレイアウトと説明の助けになる 既存アルゴリズム の例です:

.. _qgiscountpointsinpolygon:

Count points in polygon
-----------------------
Takes a point and a polygon layer and counts the number of points from the
point layer in each of the polygons of the polygon layer.
A new polygon layer is generated, with the exact same content as the input polygon
layer, but containing an additional field with the points count corresponding to
each polygon.
.. figure:: img/count_points_polygon.png
  :align: center

  The labels in the polygons show the point count

An optional weight field can be used to assign weights to each point. Alternatively,
a unique class field can be specified. If both options are used, the weight field
will take precedence and the unique class field will be ignored.

``Default menu``: :menuselection:`Vector --> Analysis Tools`

Parameters
..........

  .. list-table::
   :header-rows: 1
   :widths: 20 20 20 40
   :stub-columns: 0

   *  - Label
      - Name
      - Type
      - Description
   *  - **Polygons**
      - ``POLYGONS``
      - [vector: polygon]
      - Polygon layer whose features are associated with the count of
        points they contain
   *  - **Points**
      - ``POINTS``
      - [vector: point]
      - Point layer with features to count
   *  - **Weight field**

        Optional
      - ``WEIGHT``
      - [tablefield: numeric]
      - A field from the point layer.
        The count generated will be the sum of the weight field of the
        points contained by the polygon.
   *  - **Class field**

        Optional
      - ``CLASSFIELD``
      - [tablefield: any]
      - Points are classified based on the selected attribute and if
        several points with the same attribute value are within the
        polygon, only one of them is counted.
        The final count of the points in a polygon is, therefore, the
        count of different classes that are found in it.
   *  - **Count field name**
      - ``FIELD``
      - [string]

        Default: 'NUMPOINTS'
      - The name of the field to store the count of points
   *  - **Count**
      - ``OUTPUT``
      - [vector: polygon]

        Default: [Create temporary layer]
      - Specification of the output layer type (temporary, file,
        GeoPackage or PostGIS table).
        Encoding can also be specified.


Outputs
.......

.. list-table::
   :header-rows: 1
   :widths: 20 20 20 40
   :stub-columns: 0

   *  - Label
      - Name
      - Type
      - Description
   *  - **Count**
      - ``OUTPUT``
      - [vector: polygon]
      - Resulting layer with the attribute table containing the
        new column with the points count