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

This introductory guide will help you acquire the tools and knowledge needed to contribute to the documentation.

Read the introduction to the reStructuredText language if you are not familiar with it. Then, there are two courses of action to start contributing to the documentation:

For minor changes, such as adding a paragraph or fixing a typo, we recommend using the GitHub interface. This is the easiest and fastest way to submit changes, and it is suitable for non-technical people. Jump directly to the Contributing to the documentation section to get started.
For more complex changes, such as adding a new page, it is necessary to use Git and work from a local copy of the documentation. Follow the instructions in the Налаштування середовища section first to prepare your environment.

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

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

reStructuredText (RST)¶

The documentation is written in reStructuredText (RST), a lightweight markup language consisting of regular text augmented with markup, which allows including headings, images, notes, and so on. RST is easy to use, even if you are not familiar with it.

Важливо

Be mindful of our content and RST guidelines as you write documentation. This ensures that the documentation stays consistent and facilitates the approval of changes by the Odoo team.

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

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

First, create a GitHub account. Odoo uses GitHub to manage the source code of its products, and this is where you will submit your changes.
Створіть новий ключ 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

Install the latest release of Python and 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.
You are now ready to make your first contribution with Git.

Contributing to the documentation¶

First, create a GitHub account. Odoo uses GitHub to manage the source code of its products, and this is where you will submit your changes.
Переконайтеся, що ви переглядаєте документацію в версії, яку збираєтеся змінити. Версію можна вибрати зі спадного списку у верхньому меню.
Перейдіть на сторінку, яку ви хочете змінити, і натисніть кнопку Редагувати на GitHub у верхньому правому куті сторінки.
Натисніть кнопку Fork сховища, щоб створити fork (ваша власна копія) сховища у вашому обліковому записі. Це створює копію кодової бази, до якої можна вносити зміни, не впливаючи на основну кодову базу. Пропустіть цей крок, якщо ви працюєте в Odoo.
Внесіть потрібні зміни, дотримуючись інструкцій зміст і RST.

Порада
Натисніть кнопку Переглянути зміни, щоб переглянути свій внесок у більш зручному для читання форматі. Майте на увазі, що попередній перегляд не може правильно обробляти всі розмітки. Примітки та поради, наприклад, відображаються як простий текст.
Прокрутіть донизу сторінки та заповніть невелику форму, щоб запропонувати свої зміни. У першому текстовому полі напишіть дуже короткий підсумок ваших змін. Наприклад, «Виправити помилку» або «Додати документацію для виставлення рахунків-фактур для замовлень на продаж». У другому текстовому полі поясніть чому ви пропонуєте ці зміни. Потім натисніть кнопку Запропонувати зміни.
Перегляньте свої зміни та натисніть кнопку Створити запит на отримання.
Поставте прапорець Дозволити редагування від супроводжуючого. Пропустіть цей крок, якщо ви працюєте в Odoo.
Перегляньте резюме, яке ви написали про свої зміни, і знову натисніть кнопку Створити запит на отримання.
Унизу сторінки перевірте статус злиття та вирішіть усі проблеми.
As soon as your PR is ready for merging, a member of the Odoo team is automatically assigned for review. If the reviewer has questions or remarks, they will post them as comments and you will be notified by email. Those comments must be resolved for the contribution to go forward.
Once your changes are approved, the reviewer merges them and they appear online the next day.

Важливо

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

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

Choose the version of the documentation to which you want to make changes. Keep in mind that contributions targeting an unsupported version of Odoo are not accepted. This guide assumes that the changes target the documentation of Odoo 17, which corresponds to branch 17.0.
Create a new branch starting from branch 17.0. Prefix the branch name with the base branch: 17.0-.... If you work at Odoo, suffix the branch name with your Odoo handle: 17.0-...-xyz.
Example
```
$ git switch -c 17.0-explain-pricelists
```
```
$ git switch -c 17.0-explain-pricelists-xyz
```
Внесіть потрібні зміни, дотримуючись інструкцій зміст і RST.

Compress all PNG images that were added or modified.

$ pngquant path/to/image.png
$ mv path/to/image-fs8.png path/to/image.png

Write a redirect rule for every RST file that were renamed.
Build the documentation with make. Then, open _build/index.html in a web browser to browse the documentation with your changes.

Порада
Використовуйте make help, щоб дізнатися про інші корисні команди.
Зафіксуйте свої зміни. Напишіть чітке повідомлення коміту згідно з інструкціями в Рекомендації Git.
```
$ git add .
$ git commit
```
Push your changes to your fork, for which we added the remote alias dev.
Example
```
$ git push -u dev 17.0-explain-pricelists
```
Якщо ви працюєте в Odoo, надсилайте свої зміни безпосередньо до основної кодової бази, віддалений псевдонім якої origin.
Example
```
$ git push -u origin 17.0-explain-pricelists-xyz
```
Відкрийте PR на GitHub, щоб надіслати свої зміни на розгляд.
1. Перейдіть на сторінку порівняння кодової бази odoo/documentation.
2. Select 17.0 for the base.
3. Натисніть порівняти через forks.
4. Виберіть <your_github_account>/odoo для головного сховища. Замініть <your_github_account> назвою облікового запису GitHub, у якому ви створили fork. Пропустіть цей крок, якщо ви працюєте в Odoo.
5. Перегляньте свої зміни та натисніть кнопку Створити запит на отримання.
6. Поставте прапорець Дозволити редагування від супроводжуючого. Пропустіть цей крок, якщо ви працюєте в Odoo.
7. Завершіть опис і знову натисніть кнопку Створити запит на отримання.
Унизу сторінки перевірте статус злиття та вирішіть усі проблеми.
As soon as your PR is ready for merging, a member of the Odoo team is automatically assigned for review. If the reviewer has questions or remarks, they will post them as comments and you will be notified by email. Those comments must be resolved for the contribution to go forward.
Once your changes are approved, the reviewer merges them and they appear online the next day.

Edit on GitHub