.. _cdb_documentation:

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

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

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

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

.. code-block:: bash

   virtualenv -p python3.11 venv

або

.. code-block:: bash

   python3 -m venv venv

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

.. code-block:: bash

   source venv/bin/activate

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

.. code-block:: bash

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


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

.. code-block:: bash

   echo "127.0.0.1 mongo" >> /etc/hosts

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

.. code-block:: bash

   docker-compose up -d mongo

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

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

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

.. code-block:: bash

   py.test docs/tests

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

.. code-block:: bash

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

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

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

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

.. code-block:: bash

   make html

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

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

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

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

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

.. code-block:: bash

   make clean

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

.. code-block:: bash

   make gettext

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

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

.. code-block:: bash

   make locale-update

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

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

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

.. code-block:: bash

   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

   Текст