ドキュメンテーションガイドライン

はじめに

ここではQGISドキュメンテーションにおけるrstの利用方法について記述します。ドキュメントはサーバー時間 (太平洋時間) の0時、午前8時、午後4時に自動生成されます。現在の状況は http://docs.qgis.org で見ることができます。

See also: http://sphinx.pocoo.org/markup/inline.html or convention.rst file.

一般に, QGIS プロジェクトのrstドキュメントを作成する場合, Python documentation style guide lines <http://docs.python.org/devguide/documenting.html> にしたがって下さい_.

見出しの利用

新しい見出しを追加する場合,章,節,サブセクションとミニセクションについては以下のスタイルを使って下さい.

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

Section
=======

Subsection
----------

Minisec
.......

インラインタグ

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

    :kbd:`ctrl B`

    このように表示 Ctrl B

  • メニューgui

    :menuselection:`menu --> submenu`
  • ファイル名

    :file:`README.rst`
  • ポップアップテキストと一緒のアイコン

    |icon| :sup:`popup_text`

    (下図 image を参照).

  • ダイアログとタブタイトル

    :guilabel:`title`
  • ユーザーテキスト

    ``label``
    

脚注

注意点: 脚注は変換ソフトウェアには認識されずにPDFフォーマットには変換されません。ですので脚注はドキュメントに含めないでください。

これは脚注を作成する場合は

blabla [1]_

以下のようになります:

[1]

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

ラベル/参照

これはどこかへの参照を作成する時に使われます

.. _my_anchor:

Label/reference
===============

これは 同じページ 内の参照を呼び出します

see my_anchor_ for more information. Notice how it will jump to
the following line/thing following the 'anchor'.
Normally to declare this label you do not need to use apastroph's but
you do need to use empty lines before and after the anchor. If you use
:ref:`my_anchor` it will display the caption instead
(In this case the title of this section!)

参照1 (my_anchor) と 参照2 ラベル/参照

参照は説明文を表示する場合もあるので、文字区切りを使う必要はありません

see :ref:`my_anchor`

図とイメージ

.. _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だけで表示される図 (Figure Readme 1) の番号をするためには .. only:: html を使用してください。PDFの場合はスクリプトは自動的に生成した番号を説明の前に挿入します。

キャプション (My captionを参照)を使うには, インデントされたテキストを図ブロックの空白行の直後に入れてください。

図の参照は2つの方法で行われうる。一つは,このように参照ラベルを用いる。

(see Figure_Readme_1_).

それは、アンカーに Figure_Readme_1 を示します。望むならば、あなたは大文字を使うことができます。それは,同じ .rst 文書で使うことができますが,他の .rst 文書では使えません。

HTMLではキャプションへの参照が失われるので,あなたはこのような参照を使うことができません(それは現在**Figure 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_.

結果:

Windows Mac OSX
win osx

そしてもちろん nix を忘れていません

私の作った表,でも,これはあいにくキャプションとはみなされない。

my_drawn_table_1 のように参照することができます。

イメージ

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

置き換え

文章中に画像を入れたり,エイリアスとして使うために,どんな場所にも入れることが出来ます。画像を段落の中で使うためには,エイリアスをどこかに作成するだけです。

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

そして,それをあなたの段落の中で呼び出すだけです。

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

実際の例としてはこのようになります:

私の段落は良いロゴ nice_logo とここから始まります。

インデックス

いくつかのインデックスタグがRSTにはあります。インデックスを翻訳できるようにするために,通常テキストにまとめることが必要です。この場合,このsyntax:を使ってください。

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

もし用語が翻訳される必要がないのならば,このsyntax:を使用してください。

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

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

Here are some hints to create new, nice looking screenshots. For the user guide they go into ./resources/en/user_manual/

  • 全てのスクリーンショットは同じ環境(OS,装飾,フォントサイズ)

  • 機能を表示するのに最小のスペースまでウィンドウは小さくする (モーダルウィンドウのために全画面のスクリーンショットを撮るのはやりすぎです)

  • 散らかりが最小のものがより良い (全てのツールバーを表示する必要はありません)

  • 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 (this way, if no size is set in the rst files, images will be at original size in html and at a good print resolution in the PDF)
  • PNG形式で保存する(JPEGではなく)。

  • スクリーンショットはテキストによって内容が説明されるべきです。

  • you can find some prepared QGIS -projects that were used before to create screenshots in ./qgis-projects. This makes it easier to reproduce screenshots for the next version of QGIS. These projects use the QGIS sample dataset which should be placed in the same folder as the QGIS-Documentation Repository.
  • Use the following command to remove the global menu function in Ubuntu to create smaller application screens with menu’s.
sudo apt-get autoremove appmenu-gtk appmenu-gtk3 appmenu-qt

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

Here are some hints to create screenshots for your translated user guide. They will go into ./resources/<your language>/user_manual/

  • 全てのスクリーンショットは同じ環境(OS,装飾,フォントサイズ)

  • use the QGIS -projects included in QGIS-Documentation repository (in ./qgis_projects ). These were used to produce the ‘original’ screenshots in the manual. The QGIS Sample dataset should be placed in the same folder as the QGIS-Documentation Repository.
  • 英語の ‘original’ スクリーンショットと同様の大きさでなければ,それは引き延ばされてひどい見栄えになる。もしユーザーインターフェースの文字が長いために,異なる大きさのスクリーンショットを使う必要があるならば,その言語のドキュメントのrstコードにある寸法を変更するのを忘れてはならない。

  • 機能を表示するのに最小のスペースまでウィンドウは小さくする (モーダルウィンドウのために全画面のスクリーンショットを撮るのはやりすぎです)

  • 散らかりが最小のものがより良い (全てのツールバーを表示する必要はありません)

  • 画像エディタでリサイズしないように。サイズはrstファイルの中で設定しましょう (適切な解像度増加をせずにサイズをダウンスケールすることは醜いものとなります)

  • 背景を除く

  • PNG形式で保存する(JPEGではなく)。

  • スクリーンショットはテキストによって内容が説明されるべきです。

Documenting Processing algorithms

If you want to write documentation for Processing algorithms consider this guidelines:

  • don’t overwrite existing help files by files from other sources (e.g. QGIS source tree or Processing-Help repository), this files have different formats
  • Processing algorithm help files are part of QGIS User Guide, so use same formatting as User Guide and other documentation
  • avoid use “This algoritm does this and that...” as first sentence in algorithm description. Try to use more general words like in TauDEM or GRASS algoritms help
  • add images if needed. Use PNG format and follow general guidelines for documentation.
  • if necessary add links to additional information (e.g. publications or web-pages) to the “See also” section
  • give clear explanation for algorithm parameters and outputs (again GRASS and TauDEM are good examples).
  • don’t edit parameter or output names. If you found typo or wrong spelling — report this in bugracker, so developers can fix this in Processing code too
  • don’t list available options in algorithm description, options already listed in parameter description.
  • don’t add information vector geometry type in algorithm or parameter description without compelling reason as this information already available in parameter description