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

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

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

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

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

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

reStructuredText (RST)¶

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

Якщо вам потрібно дізнатися про певну розмітку, перейдіть до нашої шпаргалки для RST; він містить усю інформацію, яка вам може знадобитися для документації Odoo.

Важливо

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

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

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

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

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

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

Дотримуйтеся посібника з оновлення змінної PATH у Linux і macOS зі шляхом встановлення Git (за замовчуванням /usr/bin/git).
Налаштуйте Git, щоб ідентифікувати себе як автора ваших майбутніх внесків. Введіть ту саму ел. адресу, яку ви використовували для реєстрації на GitHub.
```
$ git config --global user.name “Your Name”
$ git config --global user.email “youremail@example.com”
```
Склонуйте вихідні коди за допомогою Git і перейдіть до локального сховища.
```
$ git clone git@github.com:odoo/documentation.git
$ cd documentation
```
Налаштуйте Git, щоб надсилати зміни у ваш форк, а не в основну кодову базу. У наведених нижче командах замініть <your_github_account> на ім’я облікового запису GitHub, для якого ви створили форк. Пропустіть цей крок, якщо ви працюєте в Odoo.
```
$ git remote add dev git@github.com:<your_github_account>/documentation.git
```

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

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

$ git config --global core.autocrlf true
$ git config commit.template %CD%\commit_template.txt

Установіть останню версію Python і pip на вашу машину.
Встановіть залежності Python документації за допомогою pip.
```
$ pip install -r requirements.txt
```
Переконайтеся, що каталог встановлення залежностей Python включено до системної змінної PATH.

Дотримуйтеся посібника з оновлення змінної PATH у Linux і macOS шляхом встановлення залежностей Python (за замовчуванням ~/.local/ bin).
Встановити Make.
$ sudo apt install make -y
Дотримуйтеся посібника зі встановлення Make у Windows.
Встановити pngquant.
Це воно! Ви готові зробити свій перший внесок за допомогою Git.

Зробіть свій перший внесок¶

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

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

Важливо

Деякі кроки цього посібника вимагають, щоб добре знати Git. Ось декілька навчальних посібників та інтерактивне навчання, якщо ви застрягли в якийсь момент.

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

Виберіть версію документації, до якої потрібно внести зміни. Майте на увазі, що внески, націлені на непідтримувану версію Odoo, не приймаються. Цей посібник припускає, що зміни спрямовані на документацію Odoo 14, яка відповідає гілці 14.0.
Створіть нову гілку, починаючи з гілки 14.0. Додайте перед назвою гілки базову гілку: 14.0-.... Якщо ви працюєте в Odoo, додайте до назви філії свій маркер Odoo: 14.0-...-xyz.
Example
```
$ git switch -c 14.0-explain-pricelists
```
```
$ git switch -c 14.0-explain-pricelists-xyz
```
Внесіть потрібні зміни, дотримуючись інструкцій зміст і RST.
Стисніть усі зображення PNG, які ви додали або змінили.
```
$ pngquant path/to/image.png
$ mv path/to/image-fs8.png path/to/image.png
```
Напишіть правило перенаправлення для кожного файлу RST, який ви перейменували.
Створіть документацію за допомогою make. Потім відкрийте _build/index.html у веб-браузері, щоб переглянути документацію з вашими змінами.

Порада
Використовуйте make help, щоб дізнатися про інші корисні команди.
Зафіксуйте свої зміни. Напишіть чітке повідомлення коміту згідно з інструкціями в Рекомендації Git.
```
$ git add .
$ git commit
```
Надішліть свої зміни у свій fork, для якого ми додали віддалений аліас dev.
Example
```
$ git push -u dev 14.0-explain-pricelists
```
Якщо ви працюєте в Odoo, надсилайте свої зміни безпосередньо до основної кодової бази, віддалений псевдонім якої origin.
Example
```
$ git push -u origin 14.0-explain-pricelists-xyz
```
Відкрийте PR на GitHub, щоб надіслати свої зміни на розгляд.
1. Перейдіть на сторінку порівняння кодової бази odoo/documentation.
2. Виберіть 14.0 для основи.
3. Натисніть порівняти через forks.
4. Виберіть <your_github_account>/odoo для головного сховища. Замініть <your_github_account> назвою облікового запису GitHub, у якому ви створили fork. Пропустіть цей крок, якщо ви працюєте в Odoo.
5. Перегляньте свої зміни та натисніть кнопку Створити запит на отримання.
6. Поставте прапорець Дозволити редагування від супроводжуючого. Пропустіть цей крок, якщо ви працюєте в Odoo.
7. Завершіть опис і знову натисніть кнопку Створити запит на отримання.
Унизу сторінки перевірте статус злиття та вирішіть усі проблеми.
Щойно ваш PR буде готовий до об’єднання, член команди Odoo буде автоматично призначений для перевірки. Якщо рецензент має запитання чи зауваження, він опублікує їх як коментарі, а ви отримаєте сповіщення ел. поштою. Ці коментарі мають бути вирішені, щоб внесок був продовжений.
Після схвалення ваших змін рецензент об’єднує їх, і вони з’являються в мережі наступного дня!

Edit on GitHub