Версия:

Сборка документации

Сборка документации

Документация Tarantool’а создается с помощью системы упрощенной разметки под названием Sphinx (see http://sphinx-doc.org). Вы можете создать локальную версию документации, а также содействовать в разработке версии Tarantool’а.

Необходимо установить следующие пакеты:

  • git (программа для скачивания репозиториев исходного кода)
  • CMake версии 2.8 или более новой (программа для управления процессом сборки)
  • Python версии выше 2.6 – рекомендуется 2.7 – и ниже 3.0 (Sphinx – это средство на основе Python)
  • LaTeX (система для подготовки документации; название устанавливаемого пакета обычно начинается со слов „texlive“ или „tetex“, на Ubuntu называется „texlive-latex-base“)
  • ImageMagick (система для конвертации изображений; на MacOS установите, используя brew)

Необходимо установить следующие модули Python:

  • pip любой версии

  • Sphinx версии 1.4.4 или новее

    Примечание

    Если на Mac появится сообщение ошибки «Missing SPHINX_EXECUTABLE» Mac, экспортируйте переменную PATH вручную:

    export PATH=$PATH:/User/user_name/Library/Python/2.7/bin
    
  • sphinx-intl версии 0.9.9

    Примечание

    Если на Mac появится сообщение ошибки «Missing SPHINX_INTL_DIR» Mac, экспортируйте переменную SPHINX_INTL_DIR вручную:

    export SPHINX_INTL_DIR=/User/user_name/Library/Python/2.7/bin
    
  • lupa – любой версии

Примечание

Для правильной установки модулей Python на Mac следует указать флаг --user.

Более подробную информацию об установке см. в разделе Сборка из исходных файлов данного руководства.

  1. Use git to download the latest source code of this documentation from the GitHub repository tarantool/doc, branch 1.10. For example, to download to a local directory named ~/tarantool-doc:

    $ git clone https://github.com/tarantool/doc.git ~/tarantool-doc
    
  2. Используйте CMake, чтобы начать сборку.

    $ cd ~/tarantool-doc
     $ make clean         # необязательно, добавлено на удачу
     $ rm CMakeCache.txt  # необязательно, добавлено на удачу
     $ cmake .            # начать
    
  3. Создайте локальную версию документации.

    Выполните команду make с соответствующей опцией, чтобы указать версию собираемой документации.

    $ cd ~/tarantool-doc
     $ make sphinx-html           # многостраничная английская версия
     $ make sphinx-singlehtml     # одностраничная английская версия
     $ make sphinx-html-ru        # многостраничная русская версия
     $ make sphinx-singlehtml-ru  # одностраничная русская версия
     $ make all                   # все версии плюс веб-сайт полностью
    

    Документация будет создана в поддиректориях /output:

    • /output/en (файлы английской версии)
    • /output/ru (файлы русской версии)

    Точкой входа в каждую версию будет файл index.html в соответствующей директории.

  4. Настройте веб-сервер.

    • Один способ сделать это – выполнить команду make sphinx-webserver. Веб-сервер будет настроен и запущен по порту 8000:

      $ cd ~/tarantool-doc
       $ make sphinx-html       # в качестве примера соберем многостраничную версию документации на английском языке
       $ make sphinx-webserver  # настройка и запуск веб-сервера
      

      Если порт 8000 уже используется, можно указать любой другой номер порта свыше 1000 в файле tarantool-doc/CMakeLists.txt (найдите его по sphinx-webserver) и повторно собрать файлы cmake:

      $ cd ~/tarantool-doc
       $ git clean -qfxd        # очистка старых файлов cmake
       $ cmake .                # повторная сборка файлов cmake
       $ make sphinx-html       # в качестве примера соберем многостраничную версию документации на английском языке
       $ make sphinx-webserver  # настройка и запуск веб-сервера по указанному порту
      

      Или можно освободить порт:

      $ sudo lsof -i :8000  # получение идентификатора процесса (PID)
       COMMAND PID USER FD TYPE DEVICE SIZE/OFF NODE NAME
       Python 19516 user 3u IPv4 0xe7f8gc6be1b43c7 0t0 TCP *:irdmi (LISTEN)
       $ sudo kill -9 19516  # удаление процесса
      
    • Другой способ – это запустить встроенный веб-сервер на Python. Убедитесь, что запускаете его из папки документации output:

      $ cd ~/tarantool-doc/output
       $ python -m SimpleHTTPServer 8000
      

      Если порт 8000 уже используется, можно указать любой другой номер порта свыше 1000 в файле.

  5. Open your browser and enter 127.0.0.1:8000/en/doc/1.10/ into the address box (or 127.0.0.1:8000/ru/doc/1.10/ if you built the Russian documentation). Mind the trailing slash «/» in the address string.

    Если сборка локальной документации выполнена правильно, руководство появится в окне браузера.

  6. Чтобы содействовать в разработке документации, используйте формат REST для создания чернового варианта и отправьте изменения на рассмотрение в виде запроса на включение в проект через GitHub.

    Чтобы текст соответствовал стилю и формату, воспользуйтесь рекомендациями, предоставленными в документации, здравым смыслом и уже существующими документами.

Примечание

  • Если вы предлагаете создать новый раздел документации (отдельную страницу), его следует сохранить в соответствующий раздел на GitHub.
  • Если вы хотите содействовать в локализации данной документации (например, на русский), добавьте перевод в файлы формата .po, которые хранятся в директории соответствующей локали (например, /locale/ru/LC_MESSAGES/ для русского языка). Более подробную информацию о локализации с помощью Sphinx см. по ссылке http://www.sphinx-doc.org/en/stable/intl.html