Теория разработки Qlik. Статья 4. Пользовательская документация, автоматическое обновление её на сервере и копаем AccessPoint (QV)

Время на чтение: 5 мин.

Это четвертая часть Теории разработки Qlik из …

Список будущих статей – Теории разработки Qlik

Если вам показалось что-либо непонятным, неточным, если упущен момент дзен или просто появились вопросы, приглашаю:
* Чат-группа: https://tele.click/QlikRU @QlikRU
* Информационный канал: https://tele.click/qlikd @QlikD
* Можно писать в личку: https://tele.click/Chernov @Chernov

Что нам понадобится?

  • VSCode
    • Markdown PDF – для экспорта .md-файлов в PDF
    • Markdown Preview Enhanced – для превью нашей документации
    • Markdownlint – проверка синтаксиса написания markdown-кода
    • Markdown All In One – общий модуль, в котором есть всё про markdown
  • Малость знаний html
  • Google Chrome

Markdown – что это, и почему нам это подходит?

На самом деле написание документации может быть отнесено к чему угодно, не только к пользовательской документации в рамках QlikView и использованием AccessPoint.

Я использую её на текущем этапе только для этого, вы – можете использовать для чего угодно.

Markdown – облегчённый язык разметки, созданный с целью написания наиболее читаемого и удобного для правки текста, но пригодного для преобразования в языки для продвинутых публикаций (HTML, Rich Text и других).

Все файлы, которые используются для написания документации имеют расширение .md

Почему именно MarkDown – всё просто, это мировой стандарт который практически неизменен в множестве проектов : Github, Gitlab, ReadTheDocs, WordPress (с плагином), DocuWiki, Tumblr, Magento (с плагином), TYPO3 (с плагином), Yii, Telegram и т.д. – он действительно используется повсеместно.

Самое главное! Вы пишете тексты в одном и том же стиле. Исходя из его популярности и простоты, я и решил его использовать в написании документации для пользователей QlikView.

MarkDown синтаксис, где изучить?

Существует множество статей в которых описывается синтаксис MarkDown, но я бы выделил несколько, на которые периодически сам возвращаюсь, чтобы что-то вспомнить:
* https://paulradzkov.com/2014/markdown_cheatsheet/
* https://gist.github.com/Jekins/2bf2d0638163f1294637
* https://guides.hexlet.io/markdown/

90_Documentation

Помните, во второй статье Теории разработки Qlik, я писал о каталоге 90_Documentation, сейчас пришло время разобрать его досконально.

Итак, все файлы .md я храню в этом каталоге, а картинки в подкаталоге – Images\

Но ведь тут есть еще и файлы html скажите вы, да, они тут есть, и генерируются они автоматически, из VSCode. Как это происходит? Просто! В любом месте нажимаем ПКМ(правая кнопка мышки, и выбираем пункт – Markdown PDF: Export (html))

Что еще можно делать в MarkDown? WordPress!

В данный момент, я пишу документацию не только для моих пользователей QlikView, но так же и все статьи в блоге https://qlik.pw, – все статьи у меня написаны в md-стиле, а плагин(WP-Markdown) для WordPress – преобразует его в html-код.

Вы наверно это уже успели заметить на некоторых скриншотах в разных статьях, правда?

Единственное что мне не нравится в блоге, так это css-стили, которые я доберусь исправить в свободное время. Блог будет выглядеть красивее. Но это совсем другая история…. Надеюсь сделать это до апреля 2019 года.

И еще заметил странную недоработку, а может особенность, данный плагин (WP-MarkDown) не может корректно работать со списками и не может показывать цитаты.
И еще одна проблема, не отображаются цитаты, точнее плагин не может преобразовать стандартный ключ “>” в цитату в виде html-кода

Всё решилось путём удаления плагина WP-Markdown и установкой другого – WP Editor.MD

Содержание для статей/документации

Да, содержание статей тоже можно формировать в md – автоматически, смотрите

Как ? Вызываем контекстное меню CTRL + P , далее пишем : “> mar cont”. После того как вы нажмёте Enter, или выберите этот раздел мышкой у вас внутрь файла вставится его содержимое:

Содержание формируется исходя из используемых вами разделов, я надеюсь вы уже прочитали про синтаксис?

И главное, содержание автоматически пересоздается если вы добавляете/удаляете разделы в вашей статье, что очень радует )

AccessPoint QlikView

Если вы не изменяли путь установки QlikView, то по-умолчанию, каталог с Web-файлами у нас находится тут : C:\Program Files\QlikView\Web

Как делаю я: исходя из ранее описанных статей, вы уже наверно догадались что я использую каталог 90_Documentation, с которого по-расписанию на сервере копируются все картинки и все html-файлы в Web каталог QlikView (вышеуказанный). При этом, файлы .md – не копируются.

Ах да, внутри каталога Web – я создал свой – help\ и все инструкции выгружаются именно туда

Как копировать файлы из 90_Documentation в Web\

Один очень хороший товарищ сделал мне PowerShell-скрипт, который принимает 3 параметра :
– Путь откуда
– Путь куда
– Маска

У меня два задания на сервере (через планировщик задач)
1. Копирует все html-файлы

"C:\copyFilesFromMask.ps1 D:\qlik\Dev_Documentation C:\Program Files\QlikView\Web\help html"
  1. Копирует все картинки по маске *
"C:\copyFilesFromMask.ps1 D:\qlik\Dev_Documentation\Images\ C:\Program Files\QlikView\Web\help\Images *"

Скрипт PowerShell-кода, который вы поместите в свой .ps1-файл с любым именем

from = 'D:\qlik\Dev_Documentation\'
to = 'C:\Program Files\QlikView\Web\help\'
mask = '*.html'

#from = args[0]
#to   = args[1]
#mask = '*.'+args[2]

filesList = Get-ChildItem -Path from -Filter mask

foreach (item in filesList)
{
    s1 = from+'\'+item.name
    s2 = to+'\'+item.name
    Copy-Item s1 -Destination s2 -Recurse
}

Как это выглядит?

У меня это выглядит вот так

Что нужно редактировать в AccessPoint?

Идём в каталог Web\ и открываем файл index.htm – всё лежит в нём.

Если хотите как у меня, тогда:
1. Находим строку

<a href=""><img src="images/logo_main.png" alt="QlikView" id="logo_main" /></a>
  1. После неё добавляем:
<span class="lastUpdated"><h2><a href="help/" style="color:green">Справочная информация</a></h2></span><div>   </div>

Должно получится примерно как у меня:

3. Для сохранения файла – нужны админ-права. QV останавливать не нужно

4. Чтобы проверить изменения, в браузере нужно открыть AccessPoint и нажать CTRL+F5 (для очистки кэша)

Что должен содержать в себе help\index.html

Знаете, да что угодно….

Я сделал в нём на первой странице – “Что нового”
И далее документация по приложениям…

Как то так:

Если вдруг нужно, то вот для примера .md-файл help\index.html:

# Описание справочных документов по QlikView

| Основная инструкция                                   | <a href="Qlik.html">Qlik.html</a>                            |
| ----------------------------------------------------- | :----------------------------------------------------------- |
| Показывает изменения которые происходят в приложениях | <a href="Что нового.html">Что нового.html</a>                |
| Описание приложения Сравнительный анализ              | <a href="Сравнительный анализ.html">Сравнительный анализ</a> |
| Описание приложения Продажи                           | <a href="Продажи.html">Продажи</a>                           |

Заключение

Всем Qlik