Сопровождение процесса документирования проекта pgCodeKeeper.

Единственным источником документации является сайт расположенный по адресу: https://pgcodekeeper.readthedocs.io Текущий документ описывает два рабочих процесса. Первый, это дополнение существующей документации. Второй, выполнение перевода документации.

Для внесения правок в существующую документацию нужно

1. Выполнить клонирование репозитория https://github.com/pgcodekeeper/pgcodekeeper-docs
2. Внести правки в соответствующие файлы rst. Файлы с расширением po формируются автоматически. Ручная правка этих файлов запрещена!
3. Перейти в каталог docs и выполнить файл update_messages.sh в результате выполнения будут обновлены файлы po соответствующие отредактированным rst файлам.
4. Пушим изменения в github. Если изменения были запушены в мастер, то документация на русском языке будет обновлена автоматически и будет доступна по адресу: https://pgcodekeeper.readthedocs.io/ru/latest/index.html
5. Для того, чтобы внесенные изменения стали видны на сайте переводчиков crowdin, необходимо выполнить синхронизацию документации. Для этого необходимо перейти по адресу: https://crowdin.com/project/pgcodekeeper-docs/settings#integration – настройки интеграций. Выбрать интеграцию с гитхабом и нажать кнопку “Sync now” для присоединённого репозитория.

Note: Для выполнения скрипта update_message.sh необходимо предварительно на локальной машине установить пакет sphinx-intl, установить который можно командой pip install sphinx-intl (или командой apt-get install python3-sphinx для новой версии python, затем apt-get install sphinx-intl), см. также: https://pypi.python.org/pypi/sphinx-intl/

Для выполнения перевода

1. Источником перевода является русский язык.
2. Заходим по адресу: https://crowdin.com/project/pgcodekeeper-docs и регистрируемся как контрибьюторы.
3. Выбираем po файл и переводим его на целевой язык. Не забываем нажимать «Save» после выполнения перевода ключа.

Для обновления перевода на сервере

1. Входим в режим пруфридинга в crowdin.
2. Выполняем апрув выполненного перевода.
3. Заходим на гитхаб на страничку пул-реквестов https://github.com/pgcodekeeper/pgcodekeeper-docs/pulls и принимаем сформированный пул-реквест. После принятия пул-реквсеста документация будет (через некоторое время) доступна и на сайте readthedocs. Например, для английского языка это будет: https://pgcodekeeper.readthedocs.io/en/latest/

Известные проблемы

Использование сносок [*]_ вида (с автогенерацией имени), и их локализация приводит к падению sphinx-builder. Следует использовать сноски с заданными именами. Баг sphinx.

Нелокализованные строки в английской версии приводят к падению сборки pdf. Как временное решение в conf.py явно прописано подключение babel модуля LaTeX с английским и русским языками. Последний необходимо указывать как главный язык, что приводит к локализации сгенерированных заголовков русским языком в английском pdf.

При необходимости, это возможно исправить созданием двух conf.py файлов для разных языков, и заданием их для соответствующих проектов Read the Docs. Также, данное решение можно отключить при полной локализации английской версии: сборка pdf должна перестать падать, если в ней не будет содержаться символов из неуказанных языков.

Решением этой проблемы станет возможность использования XeLaTeX движка в Read the Docs: баги 1, 2.

Локальная сборка

Тестовые локальные сборки возможно производить в докер-контейнере readthedocs/build. Последовательность команд, частично имитирующая сборку на сайте Read the Docs находится в файле rtd-docker-build.sh.