重要

翻訳はあなたが参加できるコミュニティの取り組みです。このページは現在 99.64% 翻訳されています。

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

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

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

2.1.1. 見出し 

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

本文を構成するセクションは、そのタイトルに下線（第1レベルは上線も）を引いて識別します。同じレベルのタイトルには下線の装飾に同じ文字を使う必要があります。セクションのタイトルの前には空白行をひとつ置きます。QGISドキュメントでは、chapter、section、subsectionとminisecに対して以下のスタイルを使用します。

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

Section
=======

Subsection
----------

Minisec
.......

Subminisec
^^^^^^^^^^

2.1.2. リスト 

リストはテキストを構造化するのに便利です。ここではすべてのリストに共通する簡単な規則を紹介します:

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

2.1.3. 字下げ 

reStructuredTextの字下げは、リストまたはマークアップの マーカー に合わせます。また、字下げ付きの引用ブロックを作ることもできます。仕様を参照してください

#. 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. 行内タグ 

項目を強調するためにタグを使うことができます。

メニューGUI ：サブメニューを選択したり、特定の操作、またはこのような配列の何らかの部分配列を選択するなど、メニュー選択の完全な配列をマークします。
```
:menuselection:`menu --> submenu`
```
ダイアログとタブのタイトル：ウィンドウタイトル、タブのタイトル、ボタンやオプションのラベルなど、対話的なユーザーインタフェースの一部として表示されるラベル。
```
:guilabel:`title`
```
ファイル名とディレクトリ
```
:file:`README.rst`
```
ポップアップテキスト付きアイコン
```
|iconView| :sup:`popup_text`
```
（下の画像を参照してください）。
キーボードショートカット
```
:kbd:`Ctrl+B`
```
Ctrl+B が現れます

キーボードショートカットを説明するときは、次の規則を使用してください：
- 文字キーは大文字を使って表示します: S
- 特殊キーは最初の文字を大文字にして表示します: Esc
- キーの組み合わせはキー同士の間に空白を入れずに + 記号を表示します: Shift+R
ユーザーテキスト
```
``label``
```
レイヤ、データベース、テーブル又はカラム名

レイヤ、データベース、テーブル又はカラムを参照するとき、インラインのコードで整形します:
```
``layer name``
``database_name``
``table_name``
``column_name``
```

2.1.5. ラベル／参照 

セクションやページへのハイパーリンクを作るのにテキスト内のアンカーを使うことができます。

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

.. _my_anchor:

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

同じページ 内の参照を呼び出すには次を使います

see my_anchor_ for more information.

こうなります：

see my_anchor for more information.

「アンカー」に従って行/物にジャンプすることに注目してください。アポストロフィを使う必要はありませんが、アンカーの後に空行が必要です。

ドキュメント内のどこからでも 同じ場所にジャンプする別の方法は、 :ref: 役割を使うことです。

see :ref:`my_anchor` for more information.

これはキャプション（この場合はこのセクションのタイトル！）を含むリンクを作成します：

see ラベル／参照 for more information.

つまり、参照1（my_anchor）と参照2（ラベル／参照）です。参照はしばしば完全なキャプションを表示するため、section という単語を使う必要はあまりありません。参照を説明するためにカスタムキャプションを使うこともできることに注意してください:

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

こうなります:

see Label and reference for more information.

2.1.7. 表 

次のような簡単な表を作ることができます:

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

このように表示されます:

x	y	z
1	2	3
4		5

表にはキャプションを付ける必要があります。reSTの明示的な「table」ディレクティブを使用すると、simple tables やグリッド表にキャプションを追加できます。キャプションはディレクティブと同じ行に記述し、表の先頭は少なくとも1スペース分字下げしてください。

また、表の直前にハイパーリンク先を追加して、他の場所でその表を参照できるようにすることもできます。他の参照との重複を避けるため、ハイパーリンク先は常に _table_ で始め、表のキャプションに関連する用語を使用してください。

以下は、キャプションとハイパーリンク先を含む、より複雑なグリッド表の例です:

.. _table-grid-caption:

.. table:: Grid table with caption

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

結果：

表 2.2 キャプション付きのグリッド表
Windows	macOS

and of course not to forget

複雑な表を作成するには、リスト表や CSV 表を使う方が簡単かもしれません。キャプションは、list-table または csv-table ディレクティブの後に追加してください。

これはキャプションとハイパーリンク先を持ったリスト表の例です:

.. _table-list-caption:

.. list-table:: List table with caption
   :header-rows: 1
   :widths: 20 20 20 40

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

       * Point
       * Line

結果：

表 2.3 キャプション付きのリスト表
What	目的	Key word	説明
テスト	`Useful test`	complexity	Geometry. One of: ポイント Line

表を参照するには次のように :numref: ロールを使ってください:

see :numref:`table-grid-caption` or :numref:`table-list-caption`

結果：

表 2.2 又は表 2.3 を参照

注釈

:numref: ロールを使って相互参照を作成するには、表にキャプションを加える必要があります。

2.1.8. 索引 

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

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

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

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

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

.. index:: WMS, WFS, Loading layers

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

時には、説明のいくつかのポイントを強調して、ユーザーに警告したり、注意喚起したり、ヒントを与えたりしたいことがあります。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.10. コードスニペット 

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

注釈

特別なコメント内のテキストは翻訳されますが、コードブロック内のテキストは翻訳されません。そのため、コードブロック内のコメントはできるだけ短くし、コードと関係のないコメントは避けてください。

2.1.11. 脚注 

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

blabla [1]_

これが指しているのは：

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

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

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

このリポジトリの ./qgis-projects フォルダには、スクリーンショットを作成するために用意されたQGISプロジェクトがいくつかあります。これにより、QGISの次のバージョンのスクリーンショットを簡単に再現することができます。これらのプロジェクトはQGIS Sample Data （別名Alaskaデータセット）を使用しています。解凍してQGIS-Documentation リポジトリと同じフォルダに置く必要があります。
ウィンドウは説明に必要な範囲で最小にします（小さなモーダルウィンドウのためだけに全画面表示をするのは過剰です）。
ごちゃごちゃしていないほど良いです（すべてのツールバーをアクティブにする必要はありません）。
画像編集ソフトでリサイズしないでください。サイズは必要であれば .rst ファイル中で設定されます（解像度を適切に上げることなく大きさだけを縮小すると、画像が汚くなります）。
背景はカットします。
背景が白でない場合は上部の角を透明にします。
印刷解像度は 135 dpi に設定してください（例：GIMPでは、画像 ► 画像のサイズ変更で画像を縮小し、"X/Y" を「135 ピクセル/インチ」に設定し、ファイル ► エクスポート... で書き出します）。これにより、画像はHTMLでは元のサイズで表示され、PDFでは良好な印刷解像度で出力されます。

ImageMagickのconvertコマンドを使用して画像のバッチ処理を行うこともできます:
```
convert -units PixelsPerInch input.png -density 135 output.png
```
.png で保存します (.jpeg は避けてください)。
スクリーンショットはテキストの記載に従った内容を表示していなければなりません。

Tip

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 です。

注釈

ガイドを書き始める前に、そのアルゴリズムの説明がないかどうかを確認してください。すでにある場合は、既存の説明を拡張できます。
各アルゴリズムには、プロバイダ名＋アルゴリズム自身の固有名に対応した アンカー があることが 極めて 重要です。これは、ヘルプボタンが正しいセクションのヘルプページを開くことを可能にします。アンカーはタイトルの上に配置する必要があります。例（ラベル／参照もご覧ください）:
```
.. _qgisvoronoipolygons:

Voronoi polygons
----------------
```
アルゴリズム名を調べるには、「プロセシング」ツールボックスのアルゴリズム上にマウスを置くだけです。
そのアルゴリズムが導入されたQGISのバージョンを書いてください:
```
``Added in 3.44``
```
同様に、アルゴリズムに特定のオプションの依存関係（およびバージョン）が必要かどうかについても書いてください。
```
.. attention:: Running this algorithm requires QGIS installed with <library> >= min_value
 (see :menuselection:`Help --> About` menu).
```
アルゴリズム説明の冒頭に「このアルゴリズムは、これこれこういうことをします…」という表現は避けてください。次のような、より一般的な表現を使うようにしてください:
```
Takes a point layer and generates a polygon layer containing the...
```
アルゴリズムがすることをその名前を繰り返すことで説明するのは避け、また、パラメータの名前をパラメータの説明の中で繰り返さないようにしてください。例えば、アルゴリズムが ボロノイポリゴン の場合、入力レイヤ を ポリゴンの計算に使用するレイヤ と記述することを検討してください。
説明中ではアルゴリズムにQGISのデフォルトショートカットがあるか、またはIn-place編集をサポートするのかを示します。
画像を追加してください！画像は千の言葉に値します！.png 形式を使用し、ドキュメントの一般的なガイドラインに従います（詳細は図と画像セクションを参照してください）。画像ファイルは正しいフォルダ、つまり編集中の .rst ファイルの隣にある img フォルダに置いてください。
必要に応じて、アルゴリズムに関する追加情報（例：出版物やウェブページ）を提供するリンクを「See Also」セクションに追加します。「 See also」セクションは、本当に見るべきものがある場合にのみ追加してください。グッドプラクティスとして、「See also」セクションは、類似のアルゴリズムへのリンクで埋めることができます。
アルゴリズムのパラメータと出力について明確に説明してください。既存のアルゴリズムからヒントを得てください。
アルゴリズムオプションの詳細な説明と重複しないようにします。この情報は、パラメータの説明に追加してください。
アルゴリズムやパラメータの説明にベクタジオメトリの型に関する情報を追加することは避けてください。その情報はパラメータの説明で利用できます。

パラメータのデフォルト値を追加してください。例:

* - **Number of points**
  - ``NUMBER_OF_POINTS``
  - [numeric: integer]

    Default: 1
  - Number of points to create

既存のアルゴリズムにパラメータ又はパラメータ値が追加された場合は、それが導入されたQGISのバージョンを明記してください。特定のライブラリが必要な場合は、その最小要件も併せて明記してください。

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

パラメータ／出力型	説明	視覚的な表示
ポイントベクタレイヤ	`vector: point`
ラインベクタレイヤ	`vector: line`
ポリゴンベクタレイヤ	`vector: polygon`
全ての空間ベクタレイヤ	`vector: geometry`
ジオメトリのないベクタレイヤ	`vector: table`
一般的なベクタレイヤ	`ベクタ: 任意`
ベクタフィールド数値	`tablefield: numeric`
ベクタフィールド文字列	`tablefield: string`
ベクタフィールド一般	`tablefield: any`
ラスタレイヤ	`raster`
ラスタバンド	`raster band`
HTMLファイル	`html`
式	`expression`
ラインジオメトリ	`geometry: line`
ポイントジオメトリ	`coordinates`
領域	`extent`
CRS	`crs`
列挙	`enumeration`
リスト	`list`
整数値	`numeric: integer`
小数点値	`numeric: double`
文字列	`string`
ブール値	`boolean`
フォルダパス	`フォルダ`
ファイル	`file`
行列	`matrix`
レイヤ	`layer`
出力の型は入力の型と同じ	`same as input`
Definition	`definition`
地図レイヤ	`layer` `list`
範囲（Range）	`range`
AuthConfig	`authconfig`
メッシュ	`mesh`
レイアウト	`layout`
LayoutItem	`layoutitem`
色	`color`
縮尺	`scale`
地図のテーマ	`map theme`

既存の、よく文書化されたアルゴリズムを研究し、有用なレイアウトをすべてコピーします。
作業が終わったら、貢献のためのステップバイステップに記載されているガイドラインに従って、変更をコミットし、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
   :class: longtable

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

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

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

2.1.1. 見出し 

2.1.2. リスト 

2.1.3. 字下げ 

2.1.4. 行内タグ 

2.1.5. ラベル／参照 

2.1.6. 図と画像 

画像 

アイコンの置換 

図 

2.1.7. 表 

2.1.8. 索引 

2.1.9. 特別なコメント 

2.1.10. コードスニペット 

2.1.11. 脚注 

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

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

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

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