Обновление документации

Введение

В соответствии с RFC по документации, у нас развернут общий репозиторий, объединяющий всю документацию docs_ng, и набор отдельной документации по продуктам, подключенным к этому репозиторию, таким как git submodules:

• docs_ngweb
• docs_ngmobile
• docs_ngmanager
• docs_formbuilder

Кроме того, подключена документация для разработчиков из репозиториев:

• nextgisweb
• nextgismobile lib
• nextgismobile libUI

За общим репозиторием следит buildbot, который при его изменении вызывает пересборку документации и ее опубликование.

Для получения всего репозитория вместе с подрепозиториями (submodules) необходимо выполнить команды:

git clone --depth 1 --recursive [email protected]:nextgis/docs_ng.git
cd docs_ng
git submodule foreach git checkout master
cd ./source/docs_ngweb_dev; git checkout 3; cd ../../
./switch_lang.sh ru

Т.к. все под-модули подключены по протоколу git, то наличие ssh ключа обязательно (см. https://help.github.com/articles/generating-ssh-keys/). Без ключа будет выдана ошибка клонирования репозитория.

Обновление документации при правке через интерфейс github

При выполнении изменения документации на github необходимо выполнить следующие шаги:

git submodule foreach git pull && git pull
git add .
git commit -am 'update submodules'
git push --recurse-submodules=on-demand

Для удобства указанные команды сведены в шелл-скрипт update_docs.sh, для сборки конкретного языка необходимо прееключить бранчи на ru или en. Итого обновления все документации сводится к вводу 4 команд в локальной копии репозитория docs_ng.

./switch_lang.sh ru
./update_docs.sh
./switch_lang.sh en
./update_docs.sh

После автоматической сборки следует проверить лог buildbot https://buildbot.nextgis.com - обратить внимание на красные строки в логе с ERROR

Обновление документации при локальной правке

cd source/project_name

Пишем тексты в формате rst в папку source Иллюстрации кладём в папку source/static Для просмотра выполняем

make html

и смотрим build/html/index.html

Коммитим изменения в репозиторий конкретного проекта

#из каталога конкретного проекта

git add . #добавление новых файлов
git commit -am 'fix some docs' 

Пушим в общий репозиторий документации

cd ../../
git add . #из каталога docs_ng
git commit -am 'update submodules'
git push --recurse-submodules=on-demand

Рендеринг одного раздела в отдельный pdf

Создать копию conf.py и toc.rst Заменить в conf.py в директиве latex_documents 'manual' на 'howto'

latex_documents = [
  (master_doc, 'NextGISQGIS.tex', u'Документация NextGIS QGIS',
   u'Дмитрий Барышников', 'howto', 'true'),
]

Убрать из toc.rst все ненужные разделы.

Убрать из index.rst все ненужные разделы, вот эти:

   glossary
   
Индекс и таблицы
================

* :ref:`genindex`
* :ref:`search`
* :ref:`glossary`

make latexpdf

Вернуть файлы conf.py и toc.rst обратно, удалить временные файлы, что бы случайно их не закоммитить. Или стереть всю папку.

Ещё справка по git

https://github.com/nextgis/corp/wiki/Git-Basics

Вывод в консоль содержимого всех блоков fixme из репозитория

grep -rn -A1 fixme source
или более красиво, но нужно копировать с концевыми пробелами
grep -n -A1 fixme source/*.rst | grep rst-  

Выводит

source/ui.rst-19-   Заменить скриншот на |qg|
source/ui.rst-54-   Тут вставить скрин всего окна |qg|, где главное меню отмечено красной рамкой.
source/ui.rst-66-   Тут была большая таблица, просто со списком всех пунктов меню, я её пропустил из-за отсутствия смысла и трудоёмкости перевода.
source/ui.rst-80-   Тут вставить скрин всего окна |qg|, где панели инструментов отмечены красной рамкой.
source/ui.rst-91-   уточнить названия меню
source/ui.rst-108-   Тут вставить скрин всего окна |qg|, где дерево слоёв отмечено красной рамкой.
source/ui.rst-114-   спросить, допустимо ли словосочетание "включает-выключает"
source/ui.rst-159-   Тут был список кнопок меню **Right mouse button menu for raster layers**, я его выкинул, потому что от него толка нет.