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

При обращении к документации из программ Windows-клиент и Web-клиент, пользователь по умолчанию направлен на сайт компании ДоксВижн.

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

Настройка расположения документации
Рисунок 1. Настройка расположения документации

Шаблоны расположения документации

В шаблоне могут быть использованы переменные:

  • {client} — псевдоним клиентской программы, который может приобретать значения:

    • winclient — для Windows-клиента.

    • webclient — для Web-клиента.

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

  • {version} — версия клиентской программы.

Таким образом фактический стандартный адрес документации, к примеру, для модуля Платформа версии 5.5.5 будет следующим: http://help.docsvision.com/platform/5.5.5/.

Для всех клиентских программ используется общий шаблон, поэтому размещать документацию Windows-клиента и Web-клиента следует на одном сайте.

Изменение расположения документации

Новая документация Docsvision разворачивается с помощью генератора статических сайтов Antora.

Для первой сборки сайта потребуется подключение к интернету, в будущем интернет-соединение опционально и потребуется только для получения последних изменений в документации.

Сборка сайта

Выполните указанные ниже действия последовательно:

  1. Перейдите по ссылке, скачайте и установите git.

  2. Установите Node.js предпочтительным способом или скачайте инсталлятор с официального сайта.

  3. Скопируйте на компьютер данный (Docsvision/antora-playbook) репозиторий.

    • Выполните в Powershell:

      git clone https://github.com/Docsvision/antora-playbook.git

  4. Перейдите в каталог репозитория:

    cd antora-playbook

  5. Установите Antora командой:

    npm i

  6. Откройте файл /antora-playbook/antora-playbook.yml в любом текстовом редакторе и при необходимости отредактируйте URL сайта:

    site:
  title: Документация Docsvision
  url: https://help.docsvision.com/ (1)
  robots: allow
    1 Укажите адрес сервера, на котором будет развёрнута документация.

  7. Запустите сборку сайта при помощи Antora, выполнив следующую команду в окне Powershell:

    npx antora antora-playbook.yml

  8. Файлы сайта будут расположены в папке wwwroot.

Просмотр сайта

Сайт можно просматривать:

  • Локально — нажмите на сгенерированные html-файлы, расположенные в папке wwwroot.

  • С простого http-сервера — выполните шаги ниже.

Чтобы развернуть сайт на локальном сервере:

  1. Перейдите в папку репозитория antora-playbook.

  2. Установите локальный http-сервер следующей командой:

    antora-playbook $ npm i -g http-server

  3. Выполните команду http-server, например, так:

    antora-playbook\wwwroot $ http-server build/site -c-1 -p 5000

  4. После запуска команды, локальный адрес веб-сервера будет отображён в окне консоли следующим образом:

    Starting up http-server, serving antora-playbook\wwwroot
Available on:
  http://127.0.0.1:5000
  http://192.168.1.8:5000
Hit CTRL-C to stop the server

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

Ограничения

В собранном сайте не будет работать поиск. Чтобы воспользоваться функциями локального (офлайн) поиска, рекомендуется использовать расширение Antora Lunr Search. Подробная инструкция по разворачиванию приведена по ссылке.

Перед использованием расширения Antora Lunr Search рекомендуется удалить папку antora-playbook/supplemental-ui.