Документація

• Інструкції щодо змісту
• Рекомендації та шпаргалка RST

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

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

• Для незначних змін, таких як додавання абзацу або виправлення друкарської помилки, ми рекомендуємо використовувати інтерфейс GitHub. Це найпростіший і найшвидший спосіб надсилання змін, який підходить для людей без технічних знань. Перейдіть безпосередньо до розділу Внесок у документацію, щоб розпочати.

• Для складніших змін, таких як додавання нової сторінки, необхідно використовувати Git та працювати з локальною копією документації. Спочатку дотримуйтесь інструкцій у розділі Налаштування середовища, щоб підготувати своє середовище.

Перегляньте також

Відкрийте для себе інші способи зробити внесок у Odoo

reStructuredText (RST)

Документація написана мовою reStructuredText (RST), легкою мовою розмітки, що складається зі звичайного тексту, доповненого розміткою, що дозволяє додавати заголовки, зображення, примітки тощо. RST простий у використанні, навіть якщо ви з ним не знайомі.

Важливо

Під час написання документації пам’ятайте про наші рекомендації вміст та RST. Це гарантує узгодженість документації та полегшує затвердження змін командою Odoo.

Налаштування середовища

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

1. Спочатку створіть обліковий запис GitHub. Odoo використовує GitHub для керування вихідним кодом своїх продуктів, і саме тут ви надсилатимете свої зміни.

2. Створіть новий ключ SSH і зареєструйте його у своєму обліковому записі GitHub.

3. Перейдіть на сторінку github.com/odoo/documentation і натисніть кнопку Fork у верхньому правому куті, щоб створити fork (:dfn:` ваша власна копія`) репозиторію у вашому обліковому записі. Це створює копію кодової бази, до якої можна вносити зміни, не впливаючи на основну кодову базу. Пропустіть цей крок, якщо ви працюєте в Odoo.

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

   Переконайтеся, що каталог встановлення Git включено у змінну PATH вашої системи.

   Linux and macOSWindows

   Дотримуйтеся посібника з оновлення змінної PATH у Linux і macOS зі шляхом встановлення Git (за замовчуванням /usr/bin/git).

5. Налаштуйте Git, щоб ідентифікувати себе як автора ваших майбутніх внесків. Введіть ту саму ел. адресу, яку ви використовували для реєстрації на GitHub.

   $ git config --global user.name "Your Name"
   $ git config --global user.email "youremail@example.com"
   

6. Склонуйте вихідні коди за допомогою Git і перейдіть до локального сховища.

   $ git clone git@github.com:odoo/documentation.git
   $ cd documentation
   

7. Налаштуйте Git, щоб надсилати зміни у ваш форк, а не в основну кодову базу. У наведених нижче командах замініть <your_github_account> на ім’я облікового запису GitHub, для якого ви створили форк. Пропустіть цей крок, якщо ви працюєте в Odoo.

   $ git remote add dev git@github.com:<your_github_account>/documentation.git
   

8. Налаштуйте Git, щоб полегшити співпрацю між авторами з різних систем.

   Linux and macOSWindows

   $ git config --global core.autocrlf input
   $ git config commit.template `pwd`/commit_template.txt
   

9. Встановіть останню версію Python та pip.

10. Встановіть залежності Python документації за допомогою pip.

    $ pip install -r requirements.txt
    

    Переконайтеся, що каталог встановлення залежностей Python включено до системної змінної PATH.

    Linux and macOSWindows

    Дотримуйтеся посібника з оновлення змінної PATH у Linux і macOS шляхом встановлення залежностей Python (за замовчуванням ~/.local/ bin).

11. Встановити Make.

    LinuxmacOSWindows

    $ sudo apt install make -y
    

12. Встановити pngquant.

13. Тепер ви готові зробити свій перший внесок за допомогою Git.

Внесок у документацію

Contribute from the GitHub interfaceContribute with Git

1. Спочатку створіть обліковий запис GitHub. Odoo використовує GitHub для керування вихідним кодом своїх продуктів, і саме тут ви надсилатимете свої зміни.

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

3. Перейдіть на сторінку, яку ви хочете змінити, і натисніть кнопку Редагувати на GitHub у верхньому правому куті сторінки.

4. Натисніть кнопку Fork сховища, щоб створити fork (ваша власна копія) сховища у вашому обліковому записі. Це створює копію кодової бази, до якої можна вносити зміни, не впливаючи на основну кодову базу. Пропустіть цей крок, якщо ви працюєте в Odoo.

   

5. Внесіть потрібні зміни, дотримуючись інструкцій зміст і RST.

   Порада

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

6. Прокрутіть донизу сторінки та заповніть невелику форму, щоб запропонувати свої зміни. У першому текстовому полі напишіть дуже короткий підсумок ваших змін. Наприклад, «Виправити помилку» або «Додати документацію для виставлення рахунків-фактур для замовлень на продаж». У другому текстовому полі поясніть чому ви пропонуєте ці зміни. Потім натисніть кнопку Запропонувати зміни.

   

7. Перегляньте свої зміни та натисніть кнопку Створити запит на отримання.

8. Поставте прапорець Дозволити редагування від супроводжуючого. Пропустіть цей крок, якщо ви працюєте в Odoo.

9. Перегляньте резюме, яке ви написали про свої зміни, і знову натисніть кнопку Створити запит на отримання.

10. Унизу сторінки перевірте статус злиття та вирішіть усі проблеми.

11. Щойно ваш PR буде готовий до об’єднання, член команди Odoo автоматично призначається для перевірки. Якщо у рецензента є запитання або зауваження, він опублікує їх як коментарі, про що ви отримаєте сповіщення електронною поштою. Ці коментарі мають бути вирішені, щоб внесок було продовжено.

12. Після схвалення ваших змін рецензент об’єднує їх, і вони з’являються онлайн наступного дня.