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

Генерація та оновлення документації

Підготовка середовища

  1. Створіть віртуальне середовище:

virtualenv -p python3.11 venv

або

python3 -m venv venv

  1. Активуйте віртуальне середовище:

source venv/bin/activate

  1. Встановіть необхідні залежності:

pip install -r requirements.txt
pip install -r requirements-test.txt
pip install -r docs/source/requirements.txt

4.Додайте «mongo» у /etc/hosts

echo "127.0.0.1 mongo" >> /etc/hosts

  1. Запустіть mongo за потреби:

docker-compose up -d mongo

Генерація прикладів запитів

Детальніше про тести для генерації прикладів запитів можна прочитати тут

  1. Запустіть тести що генерують приклади запитів:

py.test docs/tests

  1. За потреби запустіть окремо певний тест:

py.test docs/tests/test_belowthreshold.py -k test_docs_milestones

Генерація документації

Попередження

Наступні команди потрібно виконувати у папці docs

  1. Згенеруйте документацію

make html

Згенерована документація буде у папці build/html

Переклад документації

Попередження

Наступні команди потрібно виконувати у папці docs

Для перекладу на українську мову - uk (2-літерний ISO код мови), потрібно виконати наступні кроки:

  1. За потреби очистіть попередні згенеровані каталоги рядків.

make clean

  1. Витягніть всі рядки, що підлягають перекладу, з документації.

make gettext

Примітка

Будуть оновлені каталоги рядків .pot у папці build/locale/

  1. Оновіть переклад новими/зміненими рядками.

make locale-update

Примітка

Буде оновлено існуючі файли .po у папці locale/uk/LC_MESSAGES/ новими/зміненими рядками з каталогу згенерованого у попередньому пункті.

  1. Оновіть змінені/відсутні рядки в .po файлах в папці locale/uk/LC_MESSAGES за допомогою вашого улюбленого редактора/poedit/transifex/pootle/тощо, щоб всі переклади були повними/оновленими.

  2. Для використання перекладу у генерації документації скомпілюйте переклад.

make locale-build

Примітка

З файлів .po у папці locale/uk/LC_MESSAGES/ будуть скомпільовані .mo файли

Структура документації

TODO

Текст

Текст документації (reStructuredText/sphinx)

TODO

Текст

Тести для генерації прикладів запитів

Тести що знаходяться у папці docs/tests генерують приклади запитів виконуючи реальні запити до API. Згенеровані запити зберігаються у вигляді текстових .http файлів удиректоріях поруч з текстом документації в яких вони використовуються.

Приклад використання .http файлу у .rst файлі документації:

.. http:example:: http/tender-activating.http
   :code:

Фіксування дати в тестах для генерації запитів

TODO

Текст

Перевірка згенерованих запитів на CI

TODO

Текст

Публікація документації (readthedocs)

TODO

Текст