Важно

Перевод - это работа сообщества : ссылка:Вы можете присоединиться. Эта страница в настоящее время переводится |прогресс перевода|.

2. Рекомендации по написанию

В целом, при создании документации reST для проекта QGIS, пожалуйста, следуйте рекомендациям по стилю документации Python. Для удобства ниже приводим набор общих правил, которыми мы руководствуемся при написании документации QGIS.

2.1. Написание документации

2.1.1. Заголовки

Каждой веб-странице документации соответствует файл .rst.

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. Precede section titles with a blank line. In QGIS Documentation, you should use following styles for chapter, section, subsection and minisec.

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

Section
=======

Subsection
----------

Minisec
.......

Subminisec
^^^^^^^^^^

2.1.2. Списки

Списки полезны для структурирования текста. Вот несколько простых правил, общих для всех списков:

  • Начинайте все элементы списка с заглавной буквы

  • Не используйте знаки препинания после элементов списка, которые содержат только одно простое предложение.

  • Используйте точку ( «.») в качестве разделителя элементов списка, состоящих из нескольких предложений или одного сложного предложения.

2.1.3. Индентирование

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. Встроенные теги

Вы можете использовать теги, чтобы выделить элементы.

  • Меню GUI: для обозначения полной последовательности выбора пунктов меню, включая выбор подменю и выбор конкретной операции, или любой подпоследовательности такой последовательности.

    :menuselection:`menu --> submenu`

  • Диалоги и названия вкладок: метки, представленные как часть интерактивного пользовательского интерфейса, включая названия окон, названия вкладок, метки кнопок и опций.

    :guilabel:`title`

  • Имена файлов и каталоги

    :file:`README.rst`

  • Значки с всплывающим текстом

    |icon| :sup:`popup_text`

    (см. «изображение» ниже).

  • Горячие клавиши

    :kbd:`Ctrl+B`

    покажет Ctrl+B

    При описании сочетаний клавиш следует использовать следующие условные обозначения:

    • Буквенные клавиши отображаются заглавными буквами: S

    • Специальные клавиши отображаются с заглавной первой буквой: Esc

    • Комбинации клавиш отображаются со знаком «+» между клавишами, без пробелов: Shift+R

  • Текст пользователя

    ``label``

  • Layers, databases, tables or columns names

    When referring to layers, databases, tables or columns, format as inline code:

    ``layer name``
``database_name``
``table_name``
``column_name``

2.1.5. Этикетки/ссылки

Якоря внутри текста можно использовать для создания гиперссылок на разделы или страницы.

В примере ниже создается анкор раздела (например, метка/название ссылки).

.. _my_anchor:

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

Чтобы вызвать ссылку на той же странице, используйте

see my_anchor_ for more information.

что вернет:

См. my_anchor для получения дополнительной информации.

Обратите внимание, что он перейдет к строке/элементу, следующему за «якорем». Апострофы использовать не нужно, но после якоря должны быть пустые строки.

Другой способ перейти в одно и то же место из любой точки документации — использовать роль :ref:.

see :ref:`my_anchor` for more information.

что создаст ссылку с подписью (в данном случае с названием этого раздела!):

См. Этикетки/ссылки для получения дополнительной информации.

Итак, ссылка 1 (my_anchor) и ссылка 2 (Этикетки/ссылки). Поскольку ссылка часто отображает полную подпись, нет необходимости использовать слово section. Обратите внимание, что вы также можете использовать настраиваемую подпись для описания ссылки:

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

который возвращает:

См. :ref:`Метка и ссылка<my_anchor> ` для получения дополнительной информации.

2.1.6. Цифры и изображения

Фотографии

Чтобы вставить изображение, используйте

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

который возвращает

../../_images/logo.png

Icon substitution

You can add an image inside a text paragraph (e.g., as a tool icon). To do so, you first need to create an alias (also named substitution), which is a reference name used to display the icon. To ensure consistency across the documents and help in the use of the icons, we maintain a list in the substitutions.txt file at the root of this repository. Find more details in the Подстановки chapter.

Using an icon substitution is usually achieved through these steps:

  1. Add the icon substitution in the substitutions.txt file as below. If a substitution already exists for the icon you want to use, then skip this step.

    .. |logo| image:: /static/common/logo.png
   :width: 1 em

  2. Call it in your paragraph:

    My paragraph begins here with |logo|.

  3. Add (again) the icon substitution at the end of the file you are modifying. This helps connecting the replacement text with the actual image, and can be done by copy-pasting it from substitutions.txt or by executing the scripts/find_set_subst.py script.

    Вот как будет отображаться пример:

    My paragraph begins here with logo.

Рисунок

.. _figure_logo:

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

   A caption: A logo I like

Результат выглядит следующим образом:

../../_images/logo.png

Рис. 2.24 Подпись: Логотип, который мне нравится

Чтобы избежать конфликтов с другими ссылками, всегда начинайте якоря рисунков с «_figure_» и используйте термины, которые легко связываются с подписью к рисунку. Хотя для изображения обязательным является только выравнивание по центру, при необходимости можно использовать любые другие параметры для рисунков (такие как ширина, высота, масштаб и т. д.).

Скрипты будут вставлять автоматически сгенерированный номер перед подписью к рисунку в сгенерированных HTML- и PDF-версиях документации.

Чтобы использовать подпись (см. Моя подпись), просто вставьте отформатированный текст после пустой строки в блоке рисунка.

На рисунок можно сослаться с помощью ссылки, например так:

see :numref:`figure_logo`

отображается следующим образом:

см.:numref:figure_logo

Это предпочтительный способ ссылки на рисунки.

Примечание

Чтобы :numref: работал, рисунок должен иметь подпись.

Вместо :numref: для ссылки можно использовать :ref:, но в этом случае будет возвращаться полная подпись к изображению.

see :ref:`figure_logo`

отображается следующим образом:

см.: Подпись: Логотип, который мне нравится

2.1.7. Таблицы

You can make a simple table like this:

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

Результат будет выглядеть так:

x

y

z

1

2

3

4

5

Tables should have a caption. You can use an explicit reST «table» directive to add a caption to simple tables or grid tables. Add the caption on the same line as the directive and indent the table at least one space.

You can also add a hyperlink target before a table in order to reference it elsewhere. To avoid conflicts with other references, always begin hyperlink targets with _table_ and use terms relevant to the table caption.

Here is an example of a more complicated grid table with a caption and a hyperlink target:

.. _table-grid-caption:

.. table:: Grid table with caption

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

Результат:

Таблица 2.2 Grid table with caption

Windows

macOS

win

osx

и, конечно же, не забыть nix

You may find it easier to use list tables or CSV tables to make complex tables. Add the caption after the list-table or csv-table directive.

Here is an example of a list table with a caption and a hyperlink target:

.. _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 List table with caption

Что

Назначение

Ключевое слово

Описание

Тест

«Полезный тест»

сложность

Геометрия. Одно из следующих:

  • Точка

  • Линия

Use :numref: roles to reference tables like this:

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

Результат:

Примечание

You must add a caption to your table in order to create a cross reference with the :numref: role.

2.1.8. Index

Указатель — это удобный способ помочь читателю найти информацию в документе. Документация QGIS содержит несколько важных указателей. Существует несколько правил, которые помогают нам создать набор действительно полезных указателей (согласованных, последовательных и действительно связанных друг с другом):

  • Индекс должен быть удобочитаемым, понятным и переводимым; индекс может состоять из многих слов, но следует избегать ненужных символов «_», «-» и т. д. для их соединения, например, «Loading layers» вместо «loading_layers» или «loadingLayers».

  • Пишите с большой буквы только первую букву индекса, если только слово не имеет особого написания. Например, «Загрузка слоев», «Создание атласа», «WMS», «pgsql2shp».

  • Следите за существующим Списком индексов, чтобы повторно использовать наиболее удобное выражение с правильным написанием и избежать ненужных дубликатов.

Several index tags exist in reST. You can use the inline :index: tag within normal text:

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

Или вы можете использовать блок-уровень разметки .. index::, который связывает с началом следующего абзаца. Из-за упомянутых выше правил рекомендуется использовать блок-уровень тега:

.. index:: WMS, WFS, Loading layers

Также рекомендуется использовать такие параметры индекса, как «single», «pair» и «see», чтобы создать более структурированную и взаимосвязанную таблицу индекса. Дополнительную информацию о создании индекса см. в разделе «Создание индекса <https://www.sphinx-doc.org/en/master/usage/restructuredtext/directives.html#index-generating-markup>»_.

2.1.9. Особые комментарии

Иногда может возникнуть необходимость выделить некоторые моменты описания, чтобы предупредить, напомнить или дать пользователю подсказку. В документации QGIS мы используем специальные директивы reST, такие как «.. warning::», «.. seealso::», «.. note::» и «.. tip::». Эти директивы создают рамки, которые выделяют ваши комментарии. Дополнительную информацию см. в разделе «Разметка на уровне абзаца <https://www.sphinx-doc.org/en/master/usage/restructuredtext/directives.html#paragraph-level-markup>»_. Для предупреждений и советов требуется четкий и подходящий заголовок.

.. 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. Более подробная информация в разделе Отображение кода.

Примечание

Text in special comments will be translated, but text in code-block frames will not be translated. So keep comments in code blocks as short as possible and avoid comments unrelated to code.

2.1.11. Сноски

Это для создания сноски (отображается как пример [1]).

blabla [1]_

Что будет указывать на:

2.2. Управление снимками экрана

2.2.1. Добавить новые скриншоты

Вот несколько советов по созданию новых, красивых скриншотов. Изображения должны быть помещены в папку image (img/), которая находится в той же папке, что и ссылочный файл .rst.

  • 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 unzipped and placed in the same folder as the QGIS-Documentation Repository.

  • Уменьшите окно до минимального размера, необходимого для отображения функции (занимать весь экран для небольшого модального окна — это перебор).

  • Чем меньше беспорядка, тем лучше (нет необходимости активировать все панели инструментов)

  • Не изменяйте их размер в графическом редакторе; размер будет установлен в файлах .rst, если это необходимо (уменьшение размеров без соответствующего увеличения разрешения > некрасиво).

  • Вырезать фон

  • Сделать верхние углы прозрачными, если фон не белый

  • Set print size resolution to 135 dpi (e.g., in GIMP scale down the image using Image ► Scale Image and setting «X/Y» to 135 pixels/in, and export it through File ► Export…). This way, images will be at original size in HTML and at a good print resolution in the 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. Переведенные скриншоты

Вот несколько дополнительных советов для тех, кто хочет создать скриншоты для переведенного руководства пользователя:

Translated images should be placed in a img/<your_language>/ folder. Use the same filename as the „original“ English screenshot.

2.3. Документирование алгоритмов обработки

Если вы хотите написать документацию для алгоритмов обработки, примите во внимание следующие рекомендации:

  • Processing algorithm help files are part of QGIS User Guide, so use the same formatting as the User Guide and other documentation.

  • Документация каждого алгоритма должна быть размещена в соответствующей папке провайдера и файле группы, например, алгоритм Voronoi polygon принадлежит провайдеру 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 Этикетки/ссылки 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...

  • Избегайте описания того, что делает алгоритм, повторяя его название, и не повторяйте название параметра в описании самого параметра. Например, если алгоритм называется «Полигон Вороного», рассмотрите возможность описать «Входной слой» как «Слой для вычисления полигона».

  • Укажите в описании, имеет ли алгоритм стандартное сокращение в QGIS или поддерживает редактирование на месте.

  • Добавляйте изображения! Картинка стоит тысячи слов! Используйте формат .png и следуйте общим рекомендациям по документированию (подробнее см. раздел :ref:«Изображения») . Поместите файл изображения в соответствующую папку, т. е. в папку img рядом с файлом .rst, который вы редактируете.

  • При необходимости добавьте в раздел «См. также» ссылки, содержащие дополнительную информацию об алгоритме (например, публикации или веб-страницы). Добавляйте раздел «См. также» только в том случае, если там действительно есть что посмотреть. В качестве хорошей практики раздел «См. также» можно заполнить ссылками на похожие алгоритмы.

  • Дайте четкое объяснение параметров и результатов алгоритма: вдохновляйтесь существующими алгоритмами.

  • Избегайте дублирования подробного описания опций алгоритма. Добавьте эту информацию в описание параметров.

  • Не добавляйте информацию о типе геометрии вектора в алгоритм или описание параметра, так как эта информация уже доступна в описаниях параметров.

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

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

    Default: 1
  - Number of points to create

  • Опишите тип ввода, поддерживаемый параметрами. Доступно несколько типов, из которых вы можете выбрать один:

    Параметр/Тип вывода

    Описание

    Визуальный индикатор

    Векторный слой точек

    вектор: точка

    pointLayer

    Векторный слой линии

    вектор: линия

    lineLayer

    Векторный слой полигонов

    вектор: многоугольник

    polygonLayer

    Все пространственные векторные слои

    вектор: геометрия

    Векторный слой без геометрии

    вектор: таблица

    tableLayer

    Общий векторный слой

    вектор: любой

    Числовое векторное поле

    поле таблицы: числовое

    fieldFloat

    Векторное поле строк

    поле таблицы: строка

    fieldText

    Векторное поле общего типа

    поле таблицы: любое

    Растровый слой

    raster

    rasterLayer

    Растровая полоса

    растровый диапазон

    HTML-файл

    html

    Выражение

    выражение

    expression

    Line geometry

    geometry: line

    Геометрия точки

    координаты

    охват (extent)

    степень

    CRS

    crs

    setProjection

    Перечисление

    перечисление

    selectString

    Список

    список

    Целое значение

    числовой: целое число

    selectNumber

    Десятичное значение

    числовой: двойной

    selectNumber

    строка (string)

    string

    inputText

    логическая величина (boolean)

    boolean

    checkbox

    Путь к папке

    папка

    Файл

    файл

    Матрица

    matrix

    Слой

    слой

    Тип вывода такой же, как тип ввода

    то же, что и входные данные

    Определение

    definition

    Слои карты

    слой список

    Range/Диапазон

    range

    Автоконфигурация

    authconfig

    Сетка

    mesh

    Макет

    layout

    Элемент макета

    layoutitem

    Цвет

    color

    Масштаб

    scale

    Тема карты

    тема карты

  • Изучите существующий и хорошо документированный алгоритм и скопируйте все полезные макеты.

  • Когда вы закончите, просто следуйте инструкциям, описанным в Пошаговое руководство, чтобы зафиксировать изменения и создать Pull Request.

Here is an example of an existing algorithm to help you with the layout and the description:

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