.. _cdb_documentation:

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

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

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

.. code-block:: bash

   docker compose build


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

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

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

.. code-block:: bash

   docker compose run --rm api pytest docs/tests

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

.. code-block:: bash

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


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

.. code-block:: bash

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

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

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

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

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

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

.. code-block:: bash

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

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

.. code-block:: bash

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

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

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

.. code-block:: bash

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

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

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

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

.. code-block:: bash

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

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

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

.. admonition:: TODO

   Текст

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

.. admonition:: TODO

   Текст


.. _cdb_documentation_tests:

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

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

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

.. code-block::

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

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

.. admonition:: TODO

   Текст

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

.. admonition:: TODO

   Текст

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

.. admonition:: TODO

   Текст