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

Внески до Керівництва користувачів 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" для корейської).
  • Only edit the ENGLISH (/en) version of files. Ми використовуємо Crowdin для керування перекладами.

• All pages must be in an appropriately named sub-folder of /en (e.g. this page is in folder en/contribute/).

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

• The structure of the book is defined in SUMMARY.md.

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

TIP

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

• Images must be stored in a sub folder of /assets. Це на два рівні нижче від папок з вмістом, тому якщо ви додаєте зображення, ви посилаєтеся на нього так:

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

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

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

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

When you add a new page you must also add it to en/SUMMARY.md!

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

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

   • Put new markdown files in an appropriate sub-folder of /en/, such as /en/contribute/. Не створюйте додаткових вкладених папок.
   • Put new image files in an appropriate nested sub-folder of /assets/. Deeper nesting is allowed/encouraged.
   • Use descriptive names for folders and files. In particular, image filenames should describe what they contain (don't name as "image1.png")
   • Use lower case filenames and separate words using underscores (_).

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

   • Використовуйте найменший розмір і найнижчу роздільну здатність, яка все ще робить зображення корисним (це зменшує вартість завантаження для користувачів із слабким інтернет-з'єднанням).
   • New images should be created in a sub-folder of /assets/ (so they can be shared between translations).
   • SVG files are preferred for diagrams. PNG files are preferred over JPG for screenshots.

3. Контент

   • Use "style" (bold, emphasis, etc.) consistently and sparingly (as little as possible).
     • Жирний для натискання кнопок і визначень меню.
     • Emphasis for tool names such as QGroundControl or prettier.
     • code for file paths, and code, parameter names that aren't linked, using tools in a command line, such as prettier.
   • Headings and page titles should use "First Letter Capitalisation".
   • The page title should be a first level heading (#). All other headings should be h2 (##) or lower.
   • Не додавати ніяких стилів до заголовків.
   • Don't translate the first part of an info, tip or warning declaration (e.g. ::: tip) as this precise text is required to render the note properly.
   • Break lines on sentences by preference. Don't break lines based on some arbitrary line length.
   • Format using prettier (VSCode is a has extensions can be used for this).

4. Videos:

   • Youtube videos can be added using the format <lite-youtube videoid="<youtube-video-id>" title="your title"/> (supported via the https://www.npmjs.com/package/lite-youtube-embed custom element, which has other parameters you can pass).
     • Use instructional videos sparingly as they date badly, and are hard to maintain.
     • Cool videos of airframes in flight are always welcome.

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

Add new files in folders that cover similar topics. Then reference them in the sidebar (/en/SUMMARY.md) in line with the existing structure!

Переклади

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

Ліцензія

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