2. Writing Guidelines

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.

2.1. Writing Documentation

2.1.1. Headlines

To each webpage of the documentation corresponds a .rst file.

Sections used to structure the text are identified through their title which is underlined (and overlined for the first level). Same level titles must use same character for underline adornment. In QGIS Documentation, you should use following styles for chapter, section, subsection and minisec.

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

Section
=======

Subsection
----------

Minisec
.......

Subminisec
^^^^^^^^^^

2.1.2. Lists

Lists are useful for structuring the text. Here are some simple rules common to all lists:

• Start all list items with a capital letter

• Do not use punctuation after list items that only contain a single simple sentence

• Use period ( . ) as punctuation for list items that consist of several sentences or a single compound sentence

2.1.3. Indentation

Indentation in ReStructuredText should be aligned with the list or markup marker. It is also possible to create block quotes with indentation. See the Specification

#. In a numbered list, there should be
   three spaces when you break lines
#. And next items directly follow

   * Nested lists
   * Are also possible
   * And when they also have
     a line that is too long,
     the text should be naturally
     aligned
   * and be in their own paragraph

However, if there is an unindented paragraph, this will reset the numbering:

#. This item starts at 1 again

2.1.4. Inline Tags

You can use tags to emphasize items.

• Menu GUI: to mark a complete sequence of menu selections, including selecting submenus and choosing a specific operation, or any subsequence of such a sequence.

  :menuselection:`menu --> submenu`
  

• Dialogs and Tab titles: Labels presented as part of an interactive user interface including window titles, tab titles, button and option labels.

  :guilabel:`title`
  

• Filenames and directories

  :file:`README.rst`
  

• Icons with popup text

  |icon| :sup:`popup_text`
  

  (see image below).

• Keyboard shortcuts

  :kbd:`Ctrl+B`
  

  will show Ctrl+B

  When describing keyboard shortcuts, the following conventions should be used:

  • Letter keys are displayed using uppercase: S

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

  • Key combinations are displayed with a + sign between keys, without spaces: Shift+R

• User text

  ``label``
  

2.1.5. Labels/references

Anchors inside the text can be used to create hyperlinks to sections or pages.

The example below creates the anchor of a section (e.g., Label/reference title)

.. _my_anchor:

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

To call the reference in the same page, use

see my_anchor_ for more information.

which will return:

see my_anchor for more information.

Notice that it will jump to the line/thing following the 'anchor'. You do not need to use apostrophes, but you do need to have empty lines after the anchor.

Another way to jump to the same place from anywhere in the documentation is to use the :ref: role.

see :ref:`my_anchor` for more information.

which will create a link with the caption instead (in this case the title of this section!):

see Labels/references for more information.

So, reference 1 (my_anchor) and reference 2 (Labels/references). Because the reference often displays a full caption, it is not really necessary to use the word section. Note that you can also use a custom caption to describe the reference:

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

which returns:

see Label and reference for more information.

2.1.6. Figures and Images

Pictures

To insert an image, use

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

which returns

Replacement

You can put an image inside text or add an alias to use everywhere. To use an image inside a paragraph, first create an alias in the source/substitutions.txt file:

.. |nice_logo| image:: /static/common/logo.png
               :width: 1 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 .

To allow preview rendering in GitHub that is as close as possible to HTML rendering, you will also need to add the image replacement call at the end of the file you changed. This can be done by copy-pasting it from substitutions.txt or by executing the scripts/find_set_subst.py script.

注釈

Currently, to ensure consistency and help in the use of QGIS icons, a list of aliases is built and available in the 置換参照と定義 chapter.

Figure

.. _figure_logo:

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

   A caption: A logo I like

The result looks like this:

図 2.23 A caption: A logo I like

To avoid conflicts with other references, always begin figure anchors with _figure_ and use terms that easily connect to the figure caption. While only the centered alignment is mandatory for the image, feel free to use any other options for figures (such as width, height, scale...) if needed.

The scripts will insert an automatically generated number before the caption of the figure in the generated HTML and PDF versions of the documentation.

To use a caption (see My caption) just insert indented text after a blank line in the figure block.

A figure can be referenced using the reference label like this:

see :numref:`figure_logo`

renders like this:

see 図 2.23

This is the preferred way of referencing figures.

注釈

For :numref: to work, the figure must have a caption.

It is possible to use :ref: instead of :numref: for reference, but this returns the full caption of the image.

see :ref:`figure_logo`

renders like this:

see A caption: A logo I like

Tables

A simple table can be coded like this

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

It will render like this:

x	y	z
1	2	3
4		5

Use a \ (backslash) followed by an empty space to leave an empty space.

You can also make more complicated tables and reference them:

.. _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 it like this: my_drawn_table_.

The result:

Windows	macOS
and of course not to forget

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

You can reference to it like this my_drawn_table.

もっと複雑な表には list-table を使うのが簡単です:

.. list-table::
   :header-rows: 1
   :widths: 20 20 20 40

   * - What
     - Purpose
     - Key word
     - Description
   * - **Test**
     - ``Useful test``
     - complexity
     - Geometry.  One of:

       * Point
       * Line

The result:

What	Purpose	Key word	Description
Test	Useful test	complexity	Geometry. One of: Point Line

2.1.7. 索引

索引は読者がドキュメント内で必要な情報を見つけるのを手助けする手軽な方法です。QGISドキュメントは必須の索引項目のみを提供しています。本当に有用な（よく整理され、首尾一貫し、相互に関連づけられた）索引項目のセットのみを提供する助けとなるルールがいくつかあります。

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

• 特別な綴りを持つ単語でない限りは、索引語の最初の文字のみを大文字にします。たとえば、 Loading layers 、 Atlas generation 、 WMS 、 pgsql2shp などとします。

• 常に現在の 索引語リスト に注意を払うことで、より好適な表現を正しい綴りで再利用し、不要な重複は避けるようにしてください。

RSTには索引用のタグがあります。行内タグ :index: は通常のテキスト中で次のように使います。

QGIS can load several :index:`Vector formats` supported by GDAL ...

ブロックレベルのマークアップの .. index:: を使うこともできます。これは次の段落の始まりにリンクします。上記ルールにより、ブロックレベルタグの使用を推奨します。

.. index:: WMS, WFS, Loading layers

single 、 pair 、 see のような索引パラメータの使用も推奨します。これはより構造化され相互に関連した索引語テーブルを作るのに有用です。索引作成についてのより詳しい情報は Index generating を参照してください。

2.1.8. 特別なコメント

時には、説明のいくつかのポイントを強調して、ユーザーに警告したり、注意喚起したり、ヒントを与えたりしたいことがあります。QGIS文書では、reSTの特別なディレクティブである ... warning::, ... seealso::, ... note::, ... tip:: を使っています。これらのディレクティブは、コメントを強調するフレームを生成します。詳しくは 段落レベルのマークアップ をご覧ください。警告とヒントの両方には、明確で適切なタイトルが必要です。

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

2.1.9. コードスニペット

また、例を示したり、コードスニペットを挿入したい場合もあります。この場合、:: ディレクティブが挿入された行の下にコメントを記述します。 より良いレンダリング、特にコードに言語に合ったカラーハイライトを適用するには、code-blockディレクティブを使います（例：... code-block:: xml`. 詳細は、Showing code を参照してください。

注釈

注意書き、ヒント、警告のフレーム内のテキストは翻訳可能ですが、コードブロックのフレームは翻訳できないので注意してください。そのため、コードに関係のないコメントは避け、コメントはできるだけ短くしてください。

2.1.10. 脚注

注意：脚注はどのような翻訳ソフトでも認識されず、またpdfフォーマットにも適切に変換されません。そのため、可能であれば、文書内で脚注を使用しないでください。

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

blabla [1]_

これが指しているのは：

1

コアプラグインの更新

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

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

以下は、新しいスクリーンショットを、見た目良く作成するためのヒントです。画像ファイルは、参照元の .rst ファイルがあるフォルダの中の、画像フォルダ (img/) に置きます。

• このリポジトリの ./qgis-projects フォルダには、スクリーンショットを作成するために用意されたQGISプロジェクトがいくつかあります。これにより、QGISの次のバージョンのスクリーンショットを簡単に再現することができます。これらのプロジェクトはQGIS Sample Data （別名Alaskaデータセット）を使用しています。解凍してQGIS-Documentation Repositoryと同じフォルダに置く必要があります。

• ウィンドウは説明に必要な範囲で最小にします（小さなモーダルウィンドウのためだけに全画面表示をするのは過剰です）。

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

• 画像編集ソフトでリサイズしないでください。サイズは必要であれば .rst ファイル中で設定されます（解像度を適切に上げることなく大きさだけを縮小すると、画像が汚くなります）。

• 背景はカットします。

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

• 印刷サイズ解像度を 135 dpi に設定します（たとえば Gimp で印刷解像度を設定するにはメニューで Image ► Print size を選択して保存します）。これによって、画像はHTMLではオリジナルサイズで、PDFでは印刷に適した解像度となります。ImageMagickのconvertコマンドを使えば、この処理を次のようにバッチ処理で行うこともできます。

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

• .png で保存します (.jpeg は避けてください)。

• スクリーンショットはテキストの記載に従った内容を表示していなければなりません。

ちなみに

Ubuntuの場合、以下のコマンドでグローバルメニュー機能を取り除き、メニューを持った小さなアプリケーション画面を作ることができます:

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

2.2.2. 翻訳されたスクリーンショット

翻訳されたユーザガイド用にスクリーンショットを作成したい人向けのヒントです。

翻訳された画像は img/<your_language>/ フォルダに置きます。英語のオリジナルのスクリーンショットと同じファイル名を使用してください。

2.3. プロセシングアルゴリズムのドキュメントを作成する

プロセシングアルゴリズムのドキュメントを書きたいときは、以下のガイドラインを考慮してください。

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

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

  注釈

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

• 各アルゴリズムには、プロバイダ名＋アルゴリズム自身の固有名に対応した アンカー があることが 極めて 重要です。これは、ヘルプボタンが正しいセクションのヘルプページを開くことを可能にします。アンカーはタイトルの 上 に配置する必要があります。例 （Labels/references もご覧ください）:

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

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

• アルゴリズム説明の最初の一文に「このアルゴリズムは、これこれこういうことをします…」という表現は避けてください。次のような、より一般的な表現を使うようにしてください:

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

• アルゴリズムがすることをその名前を繰り返すことで説明するのは避け、また、パラメータの名前をパラメータの説明の中で繰り返さないようにしてください。例えば、アルゴリズムが ボロノイポリゴン の場合、入力レイヤ を ポリゴンの計算に使用するレイヤ と記述することを検討してください。

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

• 画像を追加してください！画像は千の言葉に値します！.png 形式を使用し、ドキュメントの一般的なガイドラインに従います（詳細は Figures and Images セクションを参照してください）。画像ファイルは正しいフォルダ、つまり編集中の .rst ファイルの隣にある img フォルダに置いてください。

• 必要に応じて、アルゴリズムに関する追加情報（例：出版物やウェブページ）を提供するリンクを「See Also」セクションに追加します。「 See also」セクションは、本当に見るべきものがある場合にのみ追加してください。グッドプラクティスとして、「See also」セクションは、類似のアルゴリズムへのリンクで埋めることができます。

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

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

• ベクタジオメトリのタイプに関する情報は、アルゴリズムやパラメータの説明ですでに利用できるため、追加することは避けてください。

• パラメータのデフォルト値を追加する。例:

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

• サポートされている入力の 型 を説明してください。利用できる型がいくつかあり、次から選ぶことができます：

  パラメータ／出力型	Description	Visual indicator
  ポイントベクタレイヤ	vector: point
  ラインベクタレイヤ	vector: line
  ポリゴンベクタレイヤ	vector: polygon
  Generic vector layer	ベクタ: 任意
  Vector field numeric	tablefield: numeric
  Vector field string	tablefield: string
  Vector field generic	tablefield: any
  ラスタレイヤ	raster
  ラスタバンド	raster band
  HTMLファイル	html
  Table layer	table
  式	expression
  ポイントジオメトリ	coordinates
  領域	範囲
  CRS	crs
  列挙	enumeration
  リスト	list
  数値	number
  文字列	string
  ブール値	ブール値
  フォルダパス	フォルダ
  ファイル	file
  行列	matrix
  レイヤー	layer
  出力の型は入力の型と同じ	same as input
  定義	definition
  Point	point
  マルチレイヤ	multipleLayers
  Range	range
  AuthConfig	authconfig
  メッシュ	mesh
  レイアウト	layout
  LayoutItem	layoutitem
  色	color
  縮尺	scale

• 既存の、よく文書化されたアルゴリズムを研究し、有用なレイアウトをすべてコピーします。

• 作業が終わったら、 貢献のための一歩一歩 に記載されているガイドラインに従って、変更をコミットし、Pull Request を作成するだけです。

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

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

   * - 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

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