Як писати документацію¶

Вступ¶

Це інструкція про використання RST для створення документації QGIS. Документація генерується на сервері автоматично о 0, 8am, 4pm PDT (Pacific Daylight Time). Поточний варіант доступний на http://docs.qgis.org.

Дивись також: http://sphinx.pocoo.org/markup/inline.html або файл convention.rst.

Загалом, при створенні RST документації для проекту QGIS, будь ласка, дотримуйтесь Основних принципів оформлення документації Python.

Використання заголовків¶

Додаючи нові заголовки, використовуйте наступні стилі для глав, розділів, підрозділів та секцій.

Заголовки

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

Section
=======

Subsection
----------

Minisec
.......

Теґи¶

Комбінація клавіш:
```
:kbd:`ctrl B`
```
відображається як Ctrl B
Пункти меню
```
: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:

Підпис: Логотип, який мені подобається

Використовуйте .. only:: html, щоб номер малюнка (Figure Readme 1) відображався лише у файлах HTML. Під час генерації PDF сценарій самостійно вставить автоматично згенерований номер малюнка.

Щоб підписати малюнок (див. «Підпис: Логотип, який мені подобається») просто додайте рядок з відступом після пустого рядка в блоці малюнка.

Існує два способи зробити посилання на малюнок. Перший — використовувати мітку, як показано нижче

(see Figure_Readme_1_).

В результаті буде показано якір Figure_Readme_1. За бажанням можна використовувати верхній регістр. Такі посилання можна використовувати лише всередині одно й того ж документу 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

і, звичайно, не слід забувати про

Моя таблиця, зверніть увагу, цей текст не розпізнається як підпис

Зробити посилання на таблицю можна так 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|.

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

мій абзац з красивим логотипом .

Індекс¶

RST підтримує декілька видів індексів. Щоб індекс можна було перекласти, необхідно інтегрувати його в звичайний текст. Для цього використовується наступний синтаксис:

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

Якщо термін не повинен перекладатися — використовуйте такий синтаксис:

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

використовуйте одне середовище для всіх знімків (одна ОС, те ж саме оздоблення та розмір шрифтів)
вибирайте область мінімально достатнього розміру, щоб показати все важливе (робити знімок всього екрана заради маленького модального вікна — занадто)
чим менше шуму, тим краще (не активуйте всі панелі інструментів без необхідності)
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
знімки екрана повинні відповідати тому, про що йде мова в тексті документа
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/

використовуйте одне середовище для всіх знімків (одна ОС, те ж саме оздоблення та розмір шрифтів)
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.
намагайтесь використовувати такі ж самі розміри, як і в англійській «оригінальній» версії, інакше зображення будуть розтягнені та мати поганий вигляд. Якщо необхідно використовувати інший розмір через більш довгі підписи елементів інтерфейсу, не забувайте відповідно змінити розміри в оригінальному файлі RST.
вибирайте область мінімально достатнього розміру, щоб показати все важливе (робити знімок всього екрана заради маленького модального вікна — занадто)
чим менше шуму, тим краще (не активуйте всі панелі інструментів без необхідності)
не змінюйте розмір зображень у графічному редакторі. Розмір задається у файлах RST (зменшення розмірів без відповідного збільшення роздільної здатності дає погану якість)
видаляйте фон
зберігайте зображення у форматі PNG
знімки екрана повинні відповідати тому, про що йде мова в тексті документа

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

Зміст