Напишіть документацію

Ми заохочуємо кожного користувача VyOS допомогти нам покращити нашу документацію, оскільки у нас є дефіцит, як і в більшості програмних проектів. Це допоможе не лише вам під час читання, але й усім іншим.

Якщо ви бажаєте зробити внесок у нашу документацію, це чіткий посібник, як це зробити.

Примітка

На відміну від надсилання патчів коду, немає вимоги відкривати завдання Phabricator перед надсиланням Pull-Request до документації.

VyOS documentation is written in reStructuredText and generated to Read the Docs pages with Sphinx, as per the Python tradition. We welcome all sorts of contributions to the documentation. Not just new additions but also corrections to existing documentation.

Джерело документації зберігається в сховищі Git за адресою https://github.com/vyos/vyos-documentation, і ви можете дотримуватись інструкцій у README.md, щоб створити та протестувати свої зміни.

You can either install Sphinx and build the documentation locally, or use the Dockerfile to build it in a container.

Настанови

Є кілька речей, про які слід пам’ятати, додаючи внески до документації, для послідовності та зручності читання.

Нижче наведено короткий виклад правил:

Завжди використовуйте американську англійську мову. Завжди доцільно перевірити текст через інструмент перевірки граматики та орфографії, наприклад Grammarly.
Не забудьте оновити index.rst під час додавання нового вузла.
Намагайтеся не перевищувати 80 символів у рядку, але не розбивайте URL-адреси через це.
Правильно цитуйте команди, назви файлів і короткі фрагменти коду з подвійними зворотними галочками.
Використовуйте літеральні блоки для довших фрагментів.
Залиште новий рядок перед і після заголовка.
Відступ з двома пробілами.
Якщо сумніваєтеся, дотримуйтеся стилю існуючої документації.

І, нарешті, пам’ятайте, що файли reStructuredText призначені не виключно для створення HTML і PDF. Вони мають бути зрозумілими для людини та легко переглядатися з консолі.

Вміст сторінки

Усі файли RST мають відповідати тому самому синтаксису рівня змісту та починати з них

#####
Title
#####

Папка режиму налаштування та статті охоплюють певний рівень команд. Точний рівень залежить від команди. Це має забезпечити стабільність URL-адрес, які використовуються на форумі чи в блозі.

Наприклад:

встановити зону брандмауера записується в firewall/zone.rst

set interfaces ethernet записується в interfaces/ethernet.rst

У частині сторінки конфігурації мають бути задокументовані всі можливі параметри конфігурації. Використовуйте .. cfgcmd::, як описано вище.

Відповідну команду операції необхідно задокументувати в наступній частині статті. Для цих команд використовуйте ::opcmd...

Each page must contain the following parts:

1. Theoretical information

Theoretical information required for users to understand the next document sections:

a simple explanation of what is this page about, why or when it is required to be used

references to standards, RFCs

2. Configuration description

Describe CLI items related to the service or use case. Each config line or section must be explained, using information provided in the 1st part of the page.

3. Configuration examples

Practical examples of the service or use case configuration. They must contain topology maps (if applicable) and short descriptions.

4. Known issues

This section must contain a list of:

known issues or potential problems for the service or use case

workarounds for known issues (if any exist)

5. Debugging

Described procedures for debugging a service:

how to collect logs or other debugging information (like show commands output)

how to read and what to search for in logs and collected information

what are indicators of good and bad states in debugging outputs

Керівництво по стилю

Formatting and Sphinxmarkup

Рівень TOC

Ми використовуємо наступний синтаксис для заголовків.

#####
Title
#####

********
Chapters
********

Sections
========

Subsections
-----------

Subsubsections
^^^^^^^^^^^^^^

Paragraphs
""""""""""

Перехресні посилання

Плагін використовуватиметься для створення мітки посилання для кожного заголовка. Щоб посилатися на сторінку або розділ у документації, використовуйте команду :ref:.

Наприклад, ви хочете посилатися на заголовок VLAN на сторінці ethernet.rst. Плагін генерує мітку на основі заголовка та шляху до файлу.

:ref:`configuration/interfaces/ethernet:vlan

щоб використовувати альтернативне гіперпосилання, використовуйте його таким чином:

``Перевірте VLAN<configuration/interfaces/ethernet:vlan> `

обробляти помилки збірки

Плагін попереджатиме під час створення, якщо заголовок має повторюване ім’я в тому самому документі. Щоб запобігти цьому попередженню, ви повинні розмістити спеціальне посилання вгорі заголовка.

Section A
==========

Lorem ipsum dolor sit amet, consetetur sadipscing elitr

Example
-------

Lorem ipsum dolor sit amet, consetetur sadipscing elitr

Section B
==========

Lorem ipsum dolor sit amet, consetetur sadipscing elitr

.. _section B example:

Example
-------

Lorem ipsum dolor sit amet, consetetur sadipscing elitr

Адресний простір

Зверніть увагу на такі RFC (RFC 5737, RFC 3849, RFC 5389 і RFC 7042), які описують зарезервовані публічні IP-адреси та номери автономних систем для документації:

192.0.2.0/24

198.51.100.0/24

203.0.113.0/24

2001:db8::/32

16-розрядний номер ASN: 64496 - 64511

32-розрядний номер ASN: 65536 - 65551

Одноадресні MAC-адреси: від 00-53-00 до 00-53-FF

Багатоадресні MAC-адреси: від 90-10-00 до 90-10-FF

Будь ласка, не використовуйте інший публічний адресний простір.

Довжина лінії

Обмежте всі рядки максимум 80 символами.

За винятком .. code-block::, оскільки він використовує тег html ``<pre> `` і відображає той самий формат рядка з вихідного першого файлу.

Автолінтер

Кожен запит на отримання GitHub автоматично розміщується для перевірки адресного простору та довжини рядка.

Іноді необхідно надати справжні IP-адреси, як у прикладах. Для цього використовуйте синтаксис коментаря sphinx .. stop_vyoslinter для зупинки лінтера та .. start_vyoslinter для запуску.

Спеціальна розмітка Sphinx-doc

Розроблено власні команди для написання документації. Будь ласка, влаштуйтеся з цими командами, оскільки це полегшить процес обробки документації.

cfgcmd

Під час документування команд CLI використовуйте директиву .. cfgcmd:: для всіх команд режиму налаштування. Пояснення описаної команди слід додати під цією заявою. Замінити весь вміст змінної на<value> або щось подібне.

За допомогою цих користувальницьких команд можна буде відобразити їх у більш описовий спосіб у кінцевому посібнику HTML/PDF.

.. cfgcmd:: protocols static arp <ipaddress> hwaddr <macaddress>

   This will configure a static ARP entry, always resolving `192.0.2.100` to
   `00:53:27:de:23:aa`.

Для вбудованої команди рівня конфігурації використовуйте :cfgcmd:

:cfgcmd:`set interface ethernet eth0`

Щоб отримати значення за замовчуванням із визначень XML, додайте :defaultvalue: до директиви .. cfgcmd::. Щоб мати цю функцію локально, субмодуль vyos-1x має бути ініціалізований раніше. Зверніть увагу: не оновлюйте підмодуль у своєму PR.

.. cfgcmd:: set system conntrack table-size <1-50000000>
    :defaultvalue:

    The connection tracking table contains one entry for each connection being
    tracked by the system.

opcmd

Під час документування команд робочого рівня використовуйте директиву .. opcmd::. Пояснення описаної команди слід додати під цією заявою.

За допомогою цих користувацьких команд можна відобразити їх у більш описовий спосіб у кінцевому посібнику HTML/PDF.

.. opcmd:: show protocols static arp

   Display all known ARP table entries spanning across all interfaces

Для вбудованої команди операційного рівня використовуйте :opcmd:

:opcmd:`add system image`

cmdinclude

Для мінімізації надмірності існує спеціальна директива include. Він містить текстовий файл і замінює {{ var0 }} - {{ var9 }} на правильне значення.

.. cmdinclude:: /_include/interface-address.txt
   :var0: ethernet
   :var1: eth1

вміст interface-address.txt виглядає так

.. cfgcmd:: set interfaces {{ var0 }} <interface> address <address | dhcp |
   dhcpv6>

   Configure interface `<interface>` with one or more interface
   addresses.

   * **address** can be specified multiple times as IPv4 and/or IPv6
   address, e.g. 192.0.2.1/24 and/or 2001:db8::1/64
   * **dhcp** interface address is received by DHCP from a DHCP server
   on this segment.
   * **dhcpv6** interface address is received by DHCPv6 from a DHCPv6
   server on this segment.

   Example:

   .. code-block:: none

      set interfaces {{ var0 }} {{ var1 }} address 192.0.2.1/24
      set interfaces {{ var0 }} {{ var1 }} address 192.0.2.2/24
      set interfaces {{ var0 }} {{ var1 }} address 2001:db8::ffff/64
      set interfaces {{ var0 }} {{ var1 }} address 2001:db8:100::ffff/64

vytask

Коли йдеться про завдання VyOS Phabricator, існує спеціальна команда Sphinx Markup під назвою vytask, яка автоматично відображає правильну URL-адресу Phabricator. Це широко використовується в розділі Changelog.

* :vytask:`T1605` Fixed regression in L2TP/IPsec server
* :vytask:`T1613` Netflow/sFlow captures IPv6 traffic correctly

Робочий процес розгалуження

Робочий процес Forking принципово відрізняється від інших популярних робочих процесів Git. Замість того, щоб використовувати єдине серверне сховище як «центральну» кодову базу, це надає кожному розробнику власне серверне сховище. Це означає, що кожен учасник має не одне, а два сховища Git: приватне локальне та загальнодоступне на стороні сервера.

Основна перевага робочого процесу розгалуження полягає в тому, що внески можна інтегрувати без необхідності пересилання всіх до єдиного центрального сховища. Розробники надсилають дані у власні репозиторії на стороні сервера, і лише супроводжувач проекту може надсилати дані в офіційне сховище. Це дозволяє супроводжувачу приймати коміти від будь-якого розробника, не надаючи їм доступу для запису до офіційної кодової бази.

Примітка

Оновлення нашої документації мають надсилатися за допомогою запиту на підключення GitHub. Для цього потрібен обліковий запис GitHub.

Розгалужте цей проект на GitHub https://github.com/vyos/vyos-documentation/fork
Клонуйте розгалуження на локальну машину, а потім перейдіть до цього каталогу $ cd vyos-documentation
Встановіть вимоги $ pip install -r requirements.txt (або щось подібне)
Створіть нову гілку для своєї роботи, використовуйте описову назву вашої роботи: ``$ git checkout -b<branch-name> ``
Внесіть усі ваші зміни - пам’ятайте про наші правила фіксації (Підготуйте патч/комміт). Це в основному стосується правильних повідомлень комітів, що описують вашу зміну (як і чому). Перегляньте документацію Sphinx-doc або reStructuredText, якщо ви з ними не знайомі. Це використовується для написання наших документів. Додаткові директиви, як писати в RST, можна отримати з reStructuredTextDirectives.
Перевірте свої зміни, створивши локально документацію $ make livehtml. Sphinx створить файли html у папці docs/_build. Ми пропонуємо вам контейнер Docker для зручного використання. Перевірте файл README.md цього репозиторію.
Перегляньте змінені файли, викликавши $ git status. Ви отримаєте огляд усіх змінених вами файлів. Ви можете додати окремі файли до Git Index на наступному кроці.
Додайте змінені файли до індексу Git $ git add path/to/filename або додайте всі файли без етапів $ git add .. Усі файли, додані до індексу Git, будуть частиною вас після фіксації Git.
Зафіксуйте свої зміни за допомогою повідомлення $ git commit -m "<commit message> " або скористайтеся $ git commit -v, щоб запустити ваш налаштований редактор. Ви можете ввести повідомлення про фіксацію. Знову ж таки, будь ласка, розслабтеся без правил (Підготуйте патч/комміт).
Push фіксує ваш проект GitHub: ``$ git push -u origin<branch-name> ``
Надіслати пул-запит. У GitHub відвідайте головне сховище, і ви побачите банер із пропозицією зробити запит на отримання. Заповніть форму та опишіть, що ви робите.
Після схвалення запитів на отримання ви можете також локально оновити свій розгалужений репозиторій. Спочатку вам доведеться додати другий віддалений під назвою upstream, який вказує на наше головне сховище. $ git віддалене додавання вгору https://github.com/vyos/vyos-documentation.git

Перевірте налаштовані віддалені сховища:
```
$ git remote -v
origin    https://github.com/<username>/vyos-documentation.git (fetch)
origin    https://github.com/<username>/vyos.documentation.git (push)
upstream  https://github.com/vyos/vyos-documentation.git (fetch)
upstream  https://github.com/vyos/vyos-documentation.git (push)
```
Ваше віддалене репо на Github називається origin, тоді як оригінальне репо, яке ви створили, називається upstream. Тепер ви можете локально оновлювати своє розгалужене репо.
```
$ git fetch upstream
$ git checkout current
$ git merge upstream/current
```
If you also want to update your fork on GitHub, use the following: $ git push origin current