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

Вступ¶

Це інструкція про використання 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, ...

Додавання нових знімків екрана¶

Нижче даються поради щодо створення нових знімків екрана. Знімки екрана для посібника користувача розміщено у каталозі :file:` ./resources/en/user_manual/`.

використовуйте одне середовище для всіх знімків (одна ОС, те ж саме оздоблення та розмір шрифтів)
вибирайте область мінімально достатнього розміру, щоб показати все важливе (робити знімок всього екрана заради маленького модального вікна — занадто)
чим менше шуму, тим краще (не активуйте всі панелі інструментів без необхідності)
не змінюйте розмір зображень у графічному редакторі. Розмір задається у файлах RST (зменшення розмірів без відповідного збільшення роздільної здатності дає погану якість)
видаляйте фон
встановіть роздільну здатність для друку в 135 DPI (у цьому випадку, якщо в файлі RST не задано розмір зображення, під час генерації HTML буде використовуватися оригінальний розмір, а у PDF — зображення буде високої якості)
зберігайте зображення у форматі PNG
знімки екрана повинні відповідати тому, про що йде мова в тексті документа
Проекти QGIS, які використовувалися для створення знімків екрана, можна знайти в каталозі ./qgis-projects. З їх допомогою дуже просто оновлювати знімки екрана з виходом нової версії QGIS. У проектах використовується демонстраційний набір даних, його слід розмістити у тому ж каталозі, що й документацію.
Щоб прибрати глобальне меню в Ubuntu та створювати маленькі знімки з меню, використовуйте наступну команду

sudo apt-get autoremove appmenu-gtk appmenu-gtk3 appmenu-qt

Локалізація знімків екрана¶

Нижче даються поради щодо створення локалізованих знімків екрана. Вони повинні розміщуватися у каталозі :file:` ./resources/<your language>/user_manual/`.

використовуйте одне середовище для всіх знімків (одна ОС, те ж саме оздоблення та розмір шрифтів)
використовуйте проекти QGIS з репозиторію документації (каталог ./qgis_projects). Ці проекти використовувалися для створення «оригінальних» знімків екрану. Перед їх використанням слід скопіювати демонстраційний набір даних QGIS у каталог документації.
намагайтесь використовувати такі ж самі розміри, як і в англійській «оригінальній» версії, інакше зображення будуть розтягнені та мати поганий вигляд. Якщо необхідно використовувати інший розмір через більш довгі підписи елементів інтерфейсу, не забувайте відповідно змінити розміри в оригінальному файлі RST.
вибирайте область мінімально достатнього розміру, щоб показати все важливе (робити знімок всього екрана заради маленького модального вікна — занадто)
чим менше шуму, тим краще (не активуйте всі панелі інструментів без необхідності)
не змінюйте розмір зображень у графічному редакторі. Розмір задається у файлах RST (зменшення розмірів без відповідного збільшення роздільної здатності дає погану якість)
видаляйте фон
зберігайте зображення у форматі PNG
знімки екрана повинні відповідати тому, про що йде мова в тексті документа

Documenting Processing alorithms¶

If you want to write documenation for Processing algorithm consider this guidelines:

не перезаписуйте наявні файли файлами з інших джерел (наприклад, з вихідного коду QGIS або репозиторію Processing-Help) оскільки формат файлів відрізняється
довідка алгоритмів є частиною посібника користувача, тому дотримуйтесь вимог та правил форматування, прийнятих у посібнику
уникайте використання слів «This algoritm does this and that...» в якості першого речення опису. Намагайтесь знайти більш загальні формулювання, як це зроблено у документації TauDEM та GRASS
якщо необхідно додати зображення — використовуйте формат PNG та дотримуйтесь інших вимог, що висуваються до зображень у цьому документі
якщо необхідно — додавайте посилання на додаткову інформацію (наприклад, публікації та web-сторінки) у розділ «See also»
давайте зрозумілий та вичерпний опис параметрів та результатів роботи алгоритму (гарним прикладом є документація TauDEM та GRASS)
не редагуйте назви параметрів та результатів. Якщо ви знайшли помилку — повідомте про це у багтрекері, щоб розробники змогли виправити не тільки документацію, але й сам алгоритм
don’t list availbale options in algortihm description, options already listed in parameter description.
не додавайте інформацію про тип геометрії векторного шару в опис алгоритму або параметра без нагальної потреби, оскільки ця інформація вже є частиною опису параметра

Зміст