Доповнення до документації

Внески до Керівництва користувачів PX4 дуже вітаються; від простих виправлень до правопису та граматики, до створення абсолютно нових секцій.

Ця тема пояснює, як зробити та протестувати зміни. В кінці є посібник з базового стилю.

TIP

Note Вам знадобиться обліковий запис (безкоштовно) Github щоб зробити свій внесок до цього посібника

Швидкі зміни в Github

Прості зміни до існуючого вмісту можна внести, клацнувши по посиланню Редагувати цю сторінку на GitHub, яке з'являється внизу кожної сторінки (це відкриває сторінку на GitHub для редагування).

Щоб редагувати існуючу сторінку:

1. Відкрийте сторінку
2. Клацніть Редагувати цю сторінку на GitHub посилання під вмістом сторінки.
3. Зробіть необхідні зміни.
4. Нижче редактора сторінок GitHub вас запросять створити окрему гілку, після чого вас насамперед попросять подати запит на злиття (pull request).

Команда документації перегляне запит і або об'єднає його, або працює з вами, щоб оновити його.

Зміни за допомогою Git (Нові сторінки та зображення)

Більш суттєві зміни, включаючи додавання нових сторінок або додавання/зміну зображень, не такі прості для внесення (або належним чином протестувати) на Github. Для таких змін ми рекомендуємо використовувати той самий підхід, що й для коду:

1. Використовуйте інструменти git, щоб отримати вихідний код документації на свій комп'ютер.
2. Внесіть потрібні зміни в документацію (додайте, змініть, видаліть).
3. Test перевірте, що вона будується належним чином за допомогою Vuepress.
4. Створіть гілку для ваших змін і створіть запит на витягнення (PR), щоб втягнути їх назад у документацію.

Нижче пояснено, як отримати вихідний код, побудувати локально (для тестування) та внести зміни в код.

Get/Push документація вихідного коду

Щоб отримати джерела бібліотеки(ів) на свій локальний комп'ютер, вам потрібно використовувати інструментарій git. Нижче наведено інструкції, як отримати git і використовувати його на своєму локальному комп'ютері.

1. Завантажте git для свого комп’ютера з https://git-scm.com/downloads

2. Зареєструватися на Github якщо ви ще не маєте акаунту

3. Створіть копію (форк) сховища посібника користувача PX4 на Github (інструкції тут).

4. Клонуйте ваш форкнутий репозиторій на локальний комп'ютер:

   cd ~/wherever/
   git clone https://github.com/<your git name>/PX4-user_guide.git

   Наприклад, щоб клонувати форк посібника користувача PX4 для користувача з обліковим записом Github "john_citizen":

   git clone https://github.com/john_citizen/PX4-user_guide.git

5. Перейдіть до свого локального сховища:

   cd ~/wherever/PX4-user_guide

6. Додайте remote під назвою "upstream", щоб вказувати на версію бібліотеки PX4:

   git remote add upstream https://github.com/PX4/PX4-user_guide.git

TIP

"Віддалений" - це дескриптор певного сховища. Віддалене джерело з іменем origin створюється за замовчуванням, коли ви клонуєте репозиторій, і вказує на вашу your fork розгалуження довідника. Вище ви створюєте новий віддалений _ upstream /вихідний канал_, який вказує на версію документів проекту PX4.

1. Створити гілку для ваших змін:

   git checkout -b <your_feature_branch_name>

   Це створює локальну гілку на вашому комп’ютері під назвою your_feature_branch_name.

2. Внести зміни до документації за необхідною (загальний посібник по цьому в наступних розділах)

3. Коли ви будете задоволені своїми змінами, ви можете додати їх до вашої локальної гілки за допомогою "commit":

   git add <file name>
   git commit -m "<your commit message>"

   Для зручного збереження змін, будь ласка, зверніться до розділу Управління вихідним кодом для отримання корисних порад щодо написання змістовних коментарів до комітів.

4. Натисніть "Push" вашу локальну гілку (включаючи додані до неї коміти) у вашу репозиторію-форк на Github.

   git push origin your_feature_branch_name

5. Перейдіть до вашої репозиторії-форку на Github у веб-браузері, наприклад: https://github.com/<your git name>/PX4-user_guide.git. Там ви маєте побачити повідомлення, що нова гілка була відправлена у вашу репозиторію-форк.

6. Створіть запит на витягнення (Pull Request, PR):

   • На правому боці "повідомлення про нову гілку" (див. один крок перед цим), ви повинні побачити зелену кнопку з надписом "Compare & Create Pull Request". Натисніть на неї.
   • Буде створено шаблон запиту на витягнення. Він буде перераховувати ваші коміти, і ви можете (маєте) додати значущий заголовок (у випадку одного коміту PR, це зазвичай повідомлення про коміт) та повідомлення (поясніть, що ви зробили і для якої причини. . Перевірте інші Pr реквести для порівняння)

7. Готово! Редактори PX4 User Guide зараз переглянуть вашу співпрацю і вирішать, чи хочуть вони інтегрувати її. Періодично перевіряйте, чи є у них питання по вашим змінам.

Побудова бібліотеки локально

Побудуйте бібліотеку локально, щоб перевірити, що будь-які зміни, які ви внесли, відображені належним чином:

1. Встановіть Vuepress prerequiresites:

   • Nodejs 18+
   • Yarn classic

2. Перейдіть до свого локального сховища:

   cd ~/wherever/PX4-user_guide

3. Встановити залежності (включаючи Vuepress):

   yarn install

4. Попередній перегляд і обслуговування бібліотеки:

   yarn docs:dev

   • Одного разу, коли сервер розробки / попереднього перегляду побудує бібліотеку (менше хвилини вперше), він покаже вам URL-адресу, за допомогою якої ви можете переглянути сайт. Це буде щось на кшталт: http://localhost:5173/px4_user_guide/.
   • Зупиніть обслуговування за допомогою CTRL+C у підказці терміналу.

5. Побудуйте бібліотеку за допомогою:

   # Ubuntu
   yarn docs:build
   
   # Windows
   yarn docs:buildwin

TIP

Використовуйте yarn docs:dev для попереднього перегляду як ви їх робите внесених змін (документи оновлюються та подаються дуже швидко). Перш ніж подавати PR, ви також повинні створити його за допомогою docs:build, оскільки це може висвітлити проблеми, які не видно під час використання docs:dev.

Структура Вихідного Коду

У посібнику використовується ланцюжок інструментів Vitepress.

На огляд:

• Сторінки записуються окремими файлами, використовуючи markdown.

  • Синтаксис майже такий самий, як і Github wiki.
  • Vuepress також підтримує деякі розширення markdown. Ми спробуємо та уникаємо використання цього, окрім tips, warning, etc.. Це можна переглянути – є кілька цікавих варіантів!

• Це багатомовна книга:

  • Сторінки для кожної мови зберігаються в папці з назвою для асоційованого мовного коду (наприклад, "zh" для китайської, "ko" для корейської).
  • Редагувати лише версію файлів ENGLISH (/en). Ми використовуємо Crowdin для керування перекладами.

• Всі сторінки повинні бути в відповідно названих підпапках /en (наприклад, ця сторінка знаходиться в папці en/contribute/).

  • Це полегшує створення посилань, оскільки інші сторінки і зображення завжди будуть на тому ж рівні

• Структура книги визначається у файлі SUMMARY.md

  • Якщо ви додаєте нову сторінку до посібника, вам також потрібно додати запис до цього файлу!

TIP

Це не "стандартний спосіб vuepress" для визначення бічної панелі (файл Summary імпортується в .vuepress/get_sidebar.js).

• Зображення повинні зберігатися в підпапці /assets. Це на два рівні нижче від папок з вмістом, тому якщо ви додаєте зображення, ви посилаєтеся на нього так:

  ![Image Description](../../assets/path_to_file/filename.jpg)

• Файл з назвою package.json визначає будь-які залежності збірки.

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

Додавання нових сторінок

Коли ви додаєте нову сторінку, ви також повинні додати її до / SUMMARY.md!

Інструкція зі стилістичного оформлення

1. Назви файлів/файлів

   • Розмістіть нові файли в відповідній підпапці /en/. Не створюйте додаткових вкладених папок.
   • Використовуйте описові назви. Зокрема, назви файлів із зображеннями повинні описувати їх зміст.
   • Використовуйте нижній регістр для назв файлів і розділяйте слова знаками підкреслення "_"

2. Зображення

   • Використовуйте найменший розмір і найнижчу роздільну здатність, яка все ще робить зображення корисним (це зменшує вартість завантаження для користувачів із слабким інтернет-з'єднанням).
   • Нові зображення повинні створюватися за замовчуванням у підпапці /assets/ (щоб їх можна було використовувати у всіх перекладах).

3. Контент

   • Використовуйте "стиль" (жирний, курсив і т. д.) послідовно.
     • Жирний для натискання кнопок і визначень меню.
     • Курсив для назв інструментів. В інших випадках використовуйте якомога менше.
   • Заголовки та назви сторінок повинні використовувати "Велику літеру на початку"
   • Назва сторінки повинна бути заголовком першого рівня (#). Усі інші заголовки повинні бути h2 (##) або нижче.
   • Не додавати ніяких стилів до заголовків.
   • Не перекладайте першу частину примітки, підказки чи попередження (наприклад, ::: tip) оскільки цей точний текст потрібен для належного відтворення примітки.

Де я можу додати зміни?

Додати нову документацію в рядку з існуючою структурою!

Деякі з основних категорій:

• Розробка: контент, пов’язаний із:
  • Зміни на платформі (нові режими, модулі, режими польоту, апаратне та програмне забезпечення, архітектура апаратного забезпечення та портативність).
  • "Експериментальна" робота, яка вимагає експертності розробника для відтворення.
• Політ: Пов'язана з польотом стандартного літального апарата (режими польоту, озброєння, зльот, посадка)
• Основні налаштування: Конфігурація, яку повинен виконати кожний літальний апарат
• Розширена конфігурація: Конфігурація, яка є специфічною для типу літального апарата або для певного сегмента користувачів.
• Периферії: Документація з іншого обладнання, яке можна використовувати.
  • Це також включає інформацію про налаштування та конфігурацію апаратури, яка не охоплена в Базовій конфігурації.
• Базові зборки: Збирання автопілота та його основних периферійних пристроїв
• Airframe Builds: Приклади того, як побудувати цілу систему.

Переклади

Для отримання інформації про переклад: Переклад.

Ліцензія

Вся документація PX4/Dronecode вільного використання і зміни відбуваються згідно умов дозволу CC BY 4.0 , присвяченої ліцензії.