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

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

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

docker compose build

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

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

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

docker compose run --rm api pytest docs/tests

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

docker compose run --rm api pytest docs/tests/test_belowthreshold.py -k test_docs_milestones

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

docker compose run --rm api sh -c "cd docs && make html"

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

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

Warning

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

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

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

docker compose run --rm api sh -c "cd docs && make clean"

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

docker compose run --rm api sh -c "cd docs && make gettext"

Note

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

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

docker compose run --rm api sh -c "cd docs && make locale-update"

Note

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

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

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

docker compose run --rm api sh -c "cd docs && make locale-build"

Note

З файлів .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

Текст