Документація¶
Порада
Документація на цьому сайті написана на ReStructuredText, або RST якщо коротко. Якщо Ви не знайомі з RST, перевірте RST Primer.
Ця сторінка допоможе Вам пройти квест з написанням гарної документації для проєкта UBports, яку можна буде розмістити на цьому сайті.
Настанови для документації¶
Ці правила описують як повинна бути складена документація та як уникнути проблем зі стилем, форматуванням, посиланнями та зв’язками.
Заголовок¶
Усі сторінки повинні мати назву документа, яка буде у змісті (бічна панель зліва) та вгорі сторінки.
Назви повинні бути краще «звичайними реченнями», а не «Капіталізованими Назвами». Наприклад:
Incorrect casing:
Writing A Good Bug Report
Correct casing:
Writing a good bug report
Correct casing when proper nouns are involved:
Installing Ubuntu Touch on your phone
Не існує єдиного визначення щодо правил написання назв, але звичайний стиль — це просто. Це допомагає витримати капіталізацію у змісті.
Назви сторінок підкреслюються знаками «=», Наприклад, для позначення Звіти про помилки назва виглядатиме так:
Bug reporting
=============
Зауважте:
Лише перша літера речення пишеться великою
Назву потрібно підкреслити знаками рівняння
Підкреслювати назву потрібно повністю та закінчувати останньою літерою
Неправильні приклади заголовків:
Неправильне використання великих/малих літер
Bug Reporting =============
Підкреслення закоротке
Bug reporting =====
Підкреслення задовге
Bug reporting ================
Види заголовків¶
Існує декілька рівнів заголовків, які можна розмістити на сторінці. Ці рівні зображені нижче за порядком:
Page title
==========
Level one
---------
Level two
^^^^^^^^^
Level three
"""""""""""
Слідкуйте, будь ласка, щоб у Вас виходило не більше ніж чотири рівні. Якщо Вам здається, що потрібно більше рівнів, це гарний знак, що документ краще розбити на декілька сторінок. Ба більше, вебверсія цієї документації може у змісті показати лише чотири рівні.
Зміст¶
Якщо Ви додаєте нову сторінку, Вам також потрібно додати її до змісту. Це можна зробити через додавання цієї сторінки до файла index.rst у тій самі теці, де її створили. Наприклад, якщо Ви створили файл «newpage.rst», слід додати у найближчому індексі рядок з маркуванням шевроном (>):
.. toctree::
:maxdepth: 1
:name: example-toc
oldpage
anotheroldpage
> newpage
Порядок важливий. Якщо Ви хочете, щоб Ваша сторінка з’явилася у змісті на правильному місці, розмістіть її там. У попередньому прикладі нова сторінка додана в кінці змісту.
Переміщення сторінок¶
Іноді виникає необхідність у переміщені сторінки з одного місця у документації до іншого. Загалом це потрібно для удосконалення документообігу. Наприклад, доцільніше вставляти сторінку позаду поточної редагованої сторінки в іншому розділі.
Однак люди посилаються на нашу документацію з різних джерел, які ми не контролюємо. Блоги, вебсайти та інші сайти документації можуть направляти до нас користувачів через свої посилання, які можуть ніколи не оновлюватися. Перейти за посиланням з іншого сайту й потрапити на сторінку 404 – це халепа, після якої люди змушені ще шукати інформацію в нашій документації вручну.
Ми користуємося інструментом, який називається Rediraffe, який допомагає нам уникати таких ситуацій та створює сторінки для перенаправлення, які ведуть користувачів на нові сторінки. Через це просимо Вас в разі зміни назви сторінки або її переміщення в ієрархії створювати посилання перенаправлення. Такі посилання створюються через розміщення назви файлу старого документа та імені файлу нового відносно кореня документації у файлі redirects.txt.
Також ми користуємося checkdiff від Rediraffe для перевірки, що після видалення сторінок не забули додати перенаправлення. Цей конструктор запускається як частина скрипту build.sh у репозиторії та як частина нашого автоматизованого конструктора після створення Вами запиту на злиття (MR).
Далі надаються декілька прикладів ситуацій, де потрібно створювати перенаправлення.
Ви переміщуєте systemdev/calendars.rst до appdev/calendars.rst. Тоді слід додати до файлу redirects.txt наступне:
"systemdev/calendars.txt" "appdev/calendars.txt"
Коли Ви перетворюєте appdev/clickable.rst на декілька сторінок у appdev/clickable/ додаючи більше інформації про інструмент, ніж було раніше та якщо Вами була створена вступна сторінка appdev/clickable/introduction.rst, було б гарною ідеєю перенаправити стару сторінку на нову зі вступом. Це можна зробити додаванням наступного до redirects.txt:
"appdev/clickable.rst" "appdev/clickable/introduction.rst"
Попередження¶
Ваші зміни не повинні додавати жодних попереджень до конструктора документації. Якщо виникне попередження, конструктор зупиниться з помилкою, а запит на злиття буде позначений червоним „X“. Переконайтеся, будь ласка, що Ваш RST виглядає справним до створення запиту на злиття. Це робиться автоматично (через зупинку sphinx-build з Вашою помилкою) якщо Ви притримуєтеся наших настанов до конструктора нижче.
Довжина рядка¶
Немає обмежень на довжину рядка у цьому репозиторію. Не розбивайте рядки, будь ласка, а краще увімкніть у текстовому редакторі перенесення рядків.
Процес додавання внесків¶
Наступні кроки пояснюють як можна додати внески до цієї документації.
Примітка
Для виконання цих кроків Вам потрібен обліковий запис GitLab. Якщо у Вас його немає, перейдіть на gitlab.com та створіть його.
Форк (копія) репозиторію¶
Можна створити більш професійний внесок до документації через копіювання ubports/docs.ubports.com на GitLab.
Оформлення (компіляція) документації¶
Для компіляції цієї документації виконайте кроки з інструкції на своїй локальній копії форка репозиторію.
Документацію можна створити через запуск ./build.sh у корені репозиторію. Цей скрипт створить також віртуальне оточення у ~/ubportsdocsenv в разі його відсутності.
Якщо все піде добре, Ви зможете перейти до теки _build/html, відкрити файл index.html та переглянути документацію UBports.
Якщо маєте складнощі з компіляцією документів, перша річ, яку слід спробувати — це видалення оточення конструктора. Виконайте rm -r ~/ubportsdocsenv та спробуйте ще раз.
Остання перевірка Вашого внеску¶
Після того як Ви створили на GitLab запит на злиття, система постійної інтеграції (Continuous Integration, CI) зробить тестову збірку Вашого внеску («pipeline»). Перевірте, будь ласка, двічі, що результат успішний та, що він виглядає так, як Ви очікували:
зверху вкладки «Огляд» Вашого запиту на злиття Ви побачите стан цього конвеєра (pipeline)
якщо там написано «Перевірка стану конвеєра» або «Запуск конвеєра» зачекайте ще хвилинку.
якщо «Помилка конвеєра» з червоним Х, та ще щось пішло не так, дізнайтеся про деталі за наданим посиланням
якщо «Конвеєр перевірений» з зеленою позначкою, це говорить про успішне опрацювання запиту на злиття і Ви можете продовжити з оглядом результатів
тепер, будь ласка, перейдіть за посиланням конвеєра
клацніть на завдання «зібрати»
це перенесе Вас до кінця журналу компіляції, де Ви побачите повідомлення: «Збірка успішна, перегляньте артефакти»
клацніть на посилання поруч та подивіться на повну версію документації UBports з Вашими змінами
перевірте двічі як виглядаються Ваші зміни
Альтернативні варіанти для участі¶
Переклади¶
Можливо Ви захочете перекласти частини цього документа у проєкті UBports Weblate.
Написання документів не у форматі RST¶
Якщо Ви хочете скласти документи для UBports, але Вам не зручно писати у форматі ReStructuredText, напишіть текст без форматування та розмістіть його у форумі UBports у відповідному розділі (можливо у Загальному). Хтось зможе допомогти Вам перевірити Вашу чернетку та написати потрібний текст у форматі ReStructuredText.
Незручності з Git¶
Якщо Ви склали повний документ у форматі ReStructuredText, але не почуваєте себе впевнено з Git чи GitLab, розмістіть його, будь ласка, у форумі UBports у відповідному розділі (ймовірно у Загальному). Хтось зможе допомогти Вам перевірити Вашу чернетку та пропустити її далі для долучення до цієї документації.
Поточні завдання¶
Цей розділ містить завдання, долучені до цієї документації. Якщо знаєте як щось виправити, надішліть, будь ласка, нам для удосконалення запит на злиття!
Для створення завдання, додайте такий блок до сторінки:
.. todo::
My todo text
Доробити
Розглянемо також написання документа щодо процесів із запитами на злиття.
(The original entry is located in /home/docs/checkouts/readthedocs.org/user_builds/docsubportscom-gitlab-uk/checkouts/latest/about/process/issue-tracking.rst, line 36.)
Доробити
Є також інший спосіб створити щось ефективніше за контейнери webapp, що іноді називають webapp+ або альтернативним контейнером. Це вимагає належного документування. Webapp+ — проста програма qml та легко налаштовується. Її створення таке ж просте, як і створення класичного контейнера webapp, але результат потужніший та з чудовими можливостями навігації. Доволі непоганий приклад цього є програма YouTube від Mateo Salta, який має деякі модифікації на початку шаблону.
(The original entry is located in /home/docs/checkouts/readthedocs.org/user_builds/docsubportscom-gitlab-uk/checkouts/latest/appdev/webapp/index.rst, line 19.)
Доробити
Document the process for Nexus 4 (mako)
(The original entry is located in /home/docs/checkouts/readthedocs.org/user_builds/docsubportscom-gitlab-uk/checkouts/latest/systemdev/kernel-hal.rst, line 57.)
Хостінг ReadTheDocs¶
На справді вебсайт документації зібраний та розміщений для нас проєктом Read The Docs. Наша інсталяція RTD містить один головний проєкт для англійської та один додатковий проєкт на кожну мову, додану як переклад головного проєкту. Якщо Ви супроводжуєте проєкт та хочете додати мову, створіть для початку новий проєкт ручним імпортуванням та встановіть відповідну мову. На завершення додайте цей переклад на адмінській сторінці головного проєкту.