Документация проекта ГридННС

Документация проекта ГридННС доступна по адресу http://www.ngrid.ru/docs/. Важные пункты:

Эта документация генерируется автоматически по содержимому из subversion в формате Sphinx/reStructuredText, расположенному здесь: https://svn.ngrid.ru/documentation/trunk/. Генерация документации начинается автоматически через 15 секунд после последнего commit'а в репозиторий.

Как редактировать документацию

  1. Для более удобной работы с документацией нужен пакет Sphinx. В большинстве дистрибутивов линукса соответствующий пакет для установки называется python-sphinx.
  2. Чтобы собрать локально вашу редакцию документации, проверить на наличие ошибок, посмотреть все ли нормально отформатировано и т.п. необходимо выполнить команду "make html" в директории с документацией, например installation_administration. Сгенерированный в формате html результат можно после этого наблюдать в _build/html/index.html и далее.
  3. Справка по Sphinx и reStructuredText:
  4. Если при попытке сделать commit вы получаете сообщение об ошибке, скорее всего у вас нет доступа на запись к соответствующему разделу документации. Откройте билет в компоненте "инфраструктура" с просьбой открыть доступ на запись.

Структура "Установки и администрирования компонентов ГридННС"

Назначение файлов и директорий:

  • index - основное оглавление
  • installation - оглавление инструкций по установке (написав инструкцию по установке, добавьте название файла сюда)
  • i_general - "рездел установка - общие требования к системе"
  • i_* - инструкции по установке отдельных компонентов
  • administration - оглавление инструкций по администрированию (написав инструкцию по администрированию, добавьте название файла сюда)
  • a_general - "раздел администрирование - общее"
  • a_* - инструкции по администрированию отдельных компонентов

Как же установить Sphinx и другие компоненты (при необходимости)

Sphinx

CentOS 5

yum install python-sphinx10

Для сборки документации запускать команду: 

make SPHINXBUILD=sphinx-1.0-build html

Либо сделать 

ln -s /usr/bin/sphinx-1.0-build /usr/local/bin/sphinx-build

Fedora 14

yum install python-sphinx

Для сборки документации запускать команду: 

make html

Любая unix-подобная ОС

Нужно, чтобы в системе был установлен python >= 2.4. 

wget https://bitbucket.org/ianb/virtualenv/raw/tip/virtualenv.py
python virtualenv.py --no-site-packages $HOME/sphinx
$HOME/sphinx/bin/pip install sphinx
rm virtualenv.py

Для сборки документации запускать команду: 

make SPHINXBUILD=$HOME/sphinx/bin/sphinx-build html

Pisa (xhtml2pdf)

Данный пакет нужен для генерации pdf-версии документов. Предварительные требования: python >= 2.4, freetype-devel >= 2, python-devel. Рекомендуемый метод установки: 

wget https://bitbucket.org/ianb/virtualenv/raw/tip/virtualenv.py
python virtualenv.py --no-site-packages $HOME/pisa
$HOME/pisa/bin/pip install reportlab html5lib pyPdf pisa
rm virtualenv.py
ln -s $HOME/pisa/bin/pisa /usr/local/bin

Можно устанавливать в одну среду и Sphinx и Pisa одновременно. Например: 

su -
wget https://bitbucket.org/ianb/virtualenv/raw/tip/virtualenv.py
python virtualenv.py --no-site-packages /opt/docutils
/opt/docutils/bin/pip install reportlab html5lib pyPdf pisa sphinx
rm -f virtualenv.py
ln -s -t /usr/local/bin /opt/docutils/bin/pisa /opt/docutils/bin/sphinx-build