Локальное развёртывание сайта документации

Для оперативного изменения документации вы можете редактировать страницы непосредственно на сайте GitHub. Но если вы подходите к этому вопросу более основательно, вы можете скопировать существующие файлы сайта документации в локальную папку, установить необходимые пакеты для генерации статического сайта и продолжать работу над документацией локально.

Для описываемых ниже действий пользователь должен обладать минимальными навыками работы в консоли ОС Linux.

Установка программного окружения

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

  • Git

  • Asciidoctor (для преобразования формата Asciidoc в HTML)

  • Hugo (для создания статического сайта)

Ниже приведён пример установки пакетов в Ubuntu 64-bit, который может быть легко изменён для установки пакетов в другие версии Linux или MacOS. Возможна установка и в OC Windows, хотя это потребует гораздо большего количества телодвижений. Более подробную информацию вы можете получить перейдя по ссылкам в нижней части этой страницы.

sudo apt-get update

sudo apt-get install git

Для загрузки последней версии Hugo может быть использована следующая команда:

wget https://github.com`wget -qO- https://github.com/gohugoio/hugo/releases/latest | grep -oE -m 1 '\/gohugoio\/hugo\/releases\/download\/v[0-9]+.[0-9]+.[0-9]*\/hugo_[0-9]+.[0-9]+.[0-9]*_Linux-64bit.deb'`

При необходимости можно загрузить пакет другой версии с этой страницы репозитория.

Установите скачанный пакет. Если в папке находится только один пакет Hugo, можно воспользоваться командой

sudo dpkg -i hugo*.deb

Проверить установку Hugo можно командой

hugo version

Перейдите в необходимую папку и используйте следующие команды для скачивания файлов документации и установки asciidoctor:

git clone https://github.com/salesagility/SuiteDocs.git

cd SuiteDocs

bundle install

Последняя команда скачивает и устанавливает гем asciidoctor. Проверить установку asciidoctor можно командой:

asciidoctor --version

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

Если установка необходимых пакетов прошла успешно, то всё готово к работе. В принципе для создания сайта достаточно команды

hugo

В этом случае статическая версия сайта по умолчанию будет создана в папке public.
При разработке или отладке сайта гораздо удобнее выполнить эту же команду с дополнительными параметрами:

hugo server --bind=0.0.0.0 --baseUrl=http://ip-address --navigateToChanged --enableGitInfo

где ip-address - ваш локальный ip-адрес; по умолчанию используется порт 1313, для принудительного указания порта используйте параметр --port.

При работе над сайтом документации рекомендуется запускать вышеуказанную команду в отдельном терминальном окне: в этом случае вам будут видны все сообщения сервера в реальном времени, а любые сохранённые изменения исходного текста будут сразу же преобразовываться в формат HTML и отображаться в браузере на соответствующей странице документации.

Преимущества локального развёртывания

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

Быстрое редактирование страницы документации в сочетании с автоматическим отображением в браузере только что изменённого контента весьма удобно при правке содержимого.

И, наконец, вы можете внести свой вклад не только в текст сайта, но и в его оформление и функциональность - весь код проекта документации по SuiteCRM находится в вашем распоряжении.

Content is available under GNU Free Documentation License 1.3 or later unless otherwise noted.