2. 執筆のためのガイドライン

ドキュメントを書く
- 見出し
- リスト
- 行内タグ
- Labels/references
- 図と画像
  - 画像
  - 置換
  - 図
  - 表
- 索引
- 特別なコメント
- 短いコード
- 脚注
スクリーンショットを管理する
- 新しいスクリーンショットを追加
- 翻訳されたスクリーンショット
プロセシングアルゴリズムのドキュメントを作成する

総じて、QGISプロジェクトのためにreSTドキュメントを作成するときには、 Python documentation style guidelines に従ってください。簡便のために以下に、QGISドキュメントを書く際に依拠すべき一般的なルールを、一通り示します。

2.1. ドキュメントを書く 

2.1.1. 見出し 

ドキュメントのそれぞれのウェブページには、ひとつの .rst ファイルが対応しています。

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

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

Section
=======

Subsection
----------

Minisec
.......

Subminisec
^^^^^^^^^^

2.1.2. リスト 

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

すべての項目を大文字で始めてください
単一の単文のみを含むリスト項目の後に句読点を使用しないでください
複数の文または1つの複合文からなるリスト項目の句読点としてピリオド（ . ）を使用します

2.1.3. 行内タグ 

You can use tags to emphasize items.

メニューGUI ：サブメニューを選択したり、特定の操作、またはこのような配列の何らかの部分配列を選択するなど、メニュー選択の完全な配列をマークします。
```
: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`
```
（以下の画像を参照してください）。
キーボードショートカット
```
: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``
```

2.1.4. Labels/references 

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

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

.. _my_anchor:

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

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

see my_anchor_ for more information.

これが返すのは：

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

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.

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

see :ref:`my_anchor` for more information.

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

詳細については Labels/references を参照。

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:

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

2.1.5. 図と画像 

画像 

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

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

これを返します

置換 

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

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

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

   A caption: A logo I like

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

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

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.

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

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

see :numref:`figure_logo`

renders like this:

see 図 2.18

This is the preferred way of referencing figures.

注釈

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

Avoid using :ref: instead of :numref: for reference,since this returns the full caption of the image.

see :ref:`figure_logo`

renders like this:

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

表 

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

結果：

ウィンドウズ	macOS

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

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

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

For even more complex tables, it is easier to use 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

結果：

What

目的

Key word

説明

Test

Useful test

complexity

Geometry. One of:

点
Line

2.1.6. 索引 

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

索引は、人間が読めるもの、理解できるもの、翻訳可能なものでなければなりません。索引は複数の単語から作ることができますが、それらを繋ぐ不要な _ や - などは使用しないようにしてください。たとえば loading_layers や loadingLayers ではなく、 Loading layers としてください。
特別な綴りを持つ単語でない限りは、索引語の最初の文字のみを大文字にします。たとえば、 Loading layers 、 Atlas generation 、 WMS 、 pgsql2shp などとします。
常に現在の索引語リストに注意を払うことで、より好適な表現を正しい綴りで再利用し、不要な重複は避けるようにしてください。

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

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

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

.. index:: WMS, WFS, Loading layers

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

2.1.7. 特別なコメント 

Sometimes, you may want to emphasize some points of the description, either to warn, remind or give some hints to the user. In QGIS Documentation, we use reST special directives such as .. warning::, .. seealso::`, ``.. note:: and .. tip::. These directives generate frames that highlight your comments. See Paragraph Level markup for more information. A clear and appropriate title is required for both warnings and tips.

.. 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.8. 短いコード 

You may also want to give examples and insert code snippets. In this case, write the comment below a line with the :: directive inserted. For a better rendering, especially to apply color highlighting to code according to its language, use the code-block directive, e.g. .. code-block:: xml. More details at Showing code.

注釈

While texts in note, tip and warning frames are translatable, be aware that code block frames do not allow translation. So avoid comments not related to the code and keep comments as short as possible.

2.1.9. 脚注 

Please note: Footnotes are not recognized by any translation software and it is also not converted to pdf format properly. So, if possible, don't use footnotes within any documentation.

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

blabla [1]_

これが指しているのは：

1: コアプラグインの更新

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

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

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

スクリーンショットを作成するために使うことのできるQGISプロジェクトが、このリポジトリの ./qgis-projects フォルダに用意されています。これは次期バージョンQGISのためのスクリーンショットの再作成を多少なりとも容易にします。このプロジェクトではQGISのサンプルデータ (またの名をAlaskaデータセット) を使用しています。サンプルデータはQGIS-Documentationリポジトリと同じフォルダになければなりません。
ウィンドウは説明に必要な範囲で最小にします（小さなモーダルウィンドウのためだけに全画面表示をするのは過剰です）。
ごちゃごちゃしていないほど良いです（すべてのツールバーをアクティブにする必要はありません）。
画像編集ソフトでリサイズしないでください。サイズは必要であれば .rst ファイル中で設定されます（解像度を適切に上げることなく大きさだけを縮小すると、画像が汚くなります）。
背景はカットします。
背景が白でない場合は上部の角を透明にします。
印刷サイズ解像度を 135 dpi に設定します（たとえば Gimp で印刷解像度を設定するにはメニューで Image ► Print size を選択して保存します）。これによって、画像はHTMLではオリジナルサイズで、PDFでは印刷に適した解像度となります。ImageMagickのconvertコマンドを使えば、この処理を次のようにバッチ処理で行うこともできます。
```
convert -units PixelsPerInch input.png -density 135 output.png
```
.png で保存します (.jpeg は避けてください)。
スクリーンショットはテキストの記載に従った内容を表示していなければなりません。

ちなみに

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

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

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

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

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

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

処理アルゴリズムのヘルプファイルは、QGISユーザーガイドの一部であるので、ユーザーガイドとその他の文書と同じフォーマットを使用します
各アルゴリズムのドキュメントは対応する プロバイダ フォルダと グループ ファイル中に置いてください。アルゴリズムボロノイポリゴンは QGIS プロバイダと vectorgeometry グループに属します。そのため、説明を追加する正しいファイルは source/docs/user_manual/processing_algs/qgis/vectorgeometry.rst です。

注釈

ガイドを書き始める前に、そのアルゴリズムの説明がないかどうかを確認してください。すでにある場合は、既存の説明を拡張できます。
It is extremely important that each algorithm has an anchor that corresponds to the provider name + the unique name of the algorithm itself. This allows the Help button to open the Help page of the correct section. The anchor should be placed above the title, e.g. (see also the Labels/references section):
```
.. _qgisvoronoipolygons:

Voronoi polygons
----------------
```
アルゴリズム名を調べるには、「プロセシング」ツールボックスのアルゴリズム上にマウスを置くだけです。
Avoid using "This algorithm does this and that..." as the first sentence in the algorithm description. Try to use more general expressions like:
```
Takes a point layer and generates a polygon layer containing the...
```
Avoid describing what the algorithm does by replicating its name and please don't replicate the name of the parameter in the description of the parameter itself. For example if the algorithm is Voronoi polygon consider to describe the Input layer as Layer to calculate the polygon from.
説明中ではアルゴリズムにQGISのデフォルトショートカットがあるか、またはインプレース編集をサポートするのかを示します。
Add images! A picture is worth a thousand words! Use .png format and follow the general guidelines for documentation (see the 図と画像 section for more info). Put the image file in the correct folder, i.e. the img folder next to the .rst file you are editing.
If necessary, add links in the "See also" section that provide additional information about the algorithm (e.g., publications or web-pages). Only add the "See also" section if there is really something to see. As a good practice, the "See also" section can be filled with links to similar algorithms.
アルゴリズムのパラメータと出力について明確に説明してください。既存のアルゴリズムからヒントを得てください。
Avoid duplicating detailed description of algorithm options. Add this information in the parameter description.
Avoid adding information about the vector geometry type in the algorithm or parameter description, as this information is already available in the parameter descriptions.

Add the default value of the parameter, e.g.:

* - **Number of points**
  - ``NUMBER_OF_POINTS``
  - [number]

    Default: 1
  - Number of points to create

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

Parameter/Output type	説明	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`
Point geometry	`coordinates`
領域	`範囲`
CRS	`crs`
Enumeration	`enumeration`
List	`list`
数値	`number`
文字列	`string`
真偽値	`boolean`
Folder path	`フォルダ`
ファイル	`file`
行列	`matrix`
レイヤー	`layer`
Same output type as input type	`same as input`
Definition	`definition`
点	`point`
MultipleLayers	`multipleLayers`
Range	`range`
AuthConfig	`authconfig`
メッシュ	`mesh`
Layout	`layout`
LayoutItem	`layoutitem`
Color	`color`
Scale	`scale`

Study an existing and well documented algorithm, and copy all the useful layouts.
When you are finished, just follow the guidelines described in 貢献のための一歩一歩 to commit your changes and make a 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