Важно

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

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

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

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

2.1.1. Заголовки

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

Разделы, используемые для структурирования текста, обозначаются подчёркнутым заголовком (и надчёркнутым для первого уровня). Заголовки одного уровня должны использовать одинаковый символ для подчёркивания. В документации QGIS следует использовать следующие стили для глав, разделов, подразделов и миниразделов.

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

Section
=======

Subsection
----------

Minisec
.......

Subminisec
^^^^^^^^^^

2.1.2. Списки

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

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

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

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

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

Отступы в ReStructuredText должны быть выровнены по списку или разметке marker. Также можно создавать блочные цитаты с отступами. См. Спецификация

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

  • Названия слоев

    При упоминании слоев форматируйте как встроенный код:

    ``layer 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

Замена

Вы можете вставить изображение в текст или добавить псевдоним для использования в любом месте. Чтобы использовать изображение в абзаце, сначала создайте псевдоним в файле source/substitutions.txt:

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

а затем вызовите его в своем абзаце:

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

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

Мой абзац начинается здесь с красивого логотипа nice_logo.

Чтобы сделать предварительный просмотр в GitHub максимально приближенным к отображению HTML, вам также необходимо добавить вызов замены изображения в конец измененного файла. Это можно сделать, скопировав его из файла substitutions.txt или выполнив скрипт scripts/find_set_subst.py.

Примечание

В настоящее время, чтобы обеспечить согласованность и помочь в использовании значков QGIS, создан список псевдонимов, который доступен в главе :ref:«Подстановки».

Рисунок

.. _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. Таблицы

Простая таблица может быть закодирована следующим образом

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

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

x

y

z

1

2

3

4

5

Используйте символ «» (обратный слеш), за которым следует пустое пространство, чтобы оставить пустое пространство.

Вы также можете создавать более сложные таблицы и ссылаться на них:

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

Результат:

Windows

macOS

win

osx

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

Моя нарисованная таблица, заметьте, к сожалению, это не считается подписью.

Вы можете ссылаться на него следующим образом: 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

Результат:

Что

Назначение

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

Описание

Тест

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

сложность

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

  • Точка

  • Линия

2.1.8. Index

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

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

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

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

В RST существует несколько тегов индекса. Вы можете использовать встроенный тег :index: в обычном тексте:

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

Примечание

Хотя тексты в рамках «Примечание», «Совет» и «Предупреждение» подлежат переводу, следует помнить, что рамки «Блок кода» не допускают перевода. Поэтому избегайте комментариев, не связанных с кодом, и старайтесь, чтобы комментарии были как можно короче.

2.1.11. Сноски

Обратите внимание: сноски не распознаются никаким программным обеспечением для перевода и также не конвертируются в формат pdf должным образом. Поэтому, по возможности, не используйте сноски в документации.

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

blabla [1]_

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

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

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

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

  • Вы можете найти несколько готовых проектов QGIS, которые используются для создания скриншотов, в папке ./qgis-projects этого репозитория. Это упрощает воспроизведение скриншотов для следующей версии QGIS. Эти проекты используют Sample Data (также известный как Alaska Dataset) QGIS, который необходимо распаковать и поместить в ту же папку, что и репозиторий документации QGIS.

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

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

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

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

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

  • Установите разрешение печати на «135 dpi» (например, в Gimp установите разрешение печати: меню «Изображение» –> «Размер печати» и сохраните). Таким образом, изображения будут иметь исходный размер в 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, поэтому используйте то же форматирование, что и в руководстве пользователя и другой документации.

  • Документация каждого алгоритма должна быть размещена в соответствующей папке провайдера и файле группы, например, алгоритм Voronoi polygon принадлежит провайдеру QGIS и группе vectorgeometry. Таким образом, правильный файл для добавления описания: source/docs/user_manual/processing_algs/qgis/vectorgeometry.rst.

    Примечание

    Перед тем как приступить к написанию руководства, проверьте, не описан ли алгоритм уже. В этом случае вы можете дополнить существующее описание.

  • Очень важно, чтобы каждый алгоритм имел якорь, соответствующий имени поставщика + уникальному имени самого алгоритма. Это позволяет кнопке «Справка» открывать страницу справки нужного раздела. Якорь должен быть размещен над заголовком, например (см. также раздел Этикетки/ссылки):

    .. _qgisvoronoipolygons:

Voronoi polygons
----------------

    Чтобы узнать название алгоритма, просто наведите курсор мыши на алгоритм в панели инструментов обработки.

  • Избегайте использования фразы «Этот алгоритм делает то-то и то-то…» в качестве первого предложения в описании алгоритма. Постарайтесь использовать более общие выражения, такие как:

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

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

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

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

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

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

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

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

  • Добавьте значение по умолчанию для параметра, например:

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

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

    координаты

    охват (extent)

    степень

    CRS

    crs

    setProjection

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

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

    selectString

    Список

    список

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

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

    selectNumber

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

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

    selectNumber

    строка (string)

    string

    inputText

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

    boolean

    checkbox

    Путь к папке

    папка

    Файл

    файл

    Матрица

    matrix

    Слой

    слой

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

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

    Определение

    definition

    Точка

    point

    Слои карты

    слой список

    Range/Диапазон

    range

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

    authconfig

    Сетка

    mesh

    Макет

    layout

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

    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