Декабрь'19 в Docops чате

Участников чата на день публикации: 558

Это краткое резюме дискуссий и полезных ссылок в чате Docops в декабре 2019.

выбор SSG

фильтры pandoc

сбор фидбека к документации (CSAT)

метатеги в Markdown

генерация документации в PDF при использовании MkDocs

сравнение двух текстовых pdf-файлов

Docusaurus 2

1.12

Что обсуждали: выбор SSG

@murgut спросил, существует ли либа, которая будет соответствовать этим требованиям: подсветка кода, вывод документа единым списком, подсветка аннотаций, встраивание движка для интерактивных примеров, мобильная версия, поддержка <head> тегов, пререндер html.
@NickVolynkin ответил, что подсветка синтаксиса обычно реализовывается отдельными библиотеками (pygments, rouge, т.д.), пререндер html есть почти везде, теги в head также почти везде, где можно редактировать шаблон, мобильная версия зависит от темы. В остальном, лучше выбрать что-то из http://staticgen.com лучше на JS, если это ваш основной язык. @DarthVader добавил, что есть еще highlight.js.
Сайт reactjs сделан на движке Gatsby https://github.com/reactjs/reactjs.org#running-locally.

10.12

@ligurio порекомендовал тьюториал по написанию документации для Unix - https://manpages.bsd.lv/mdoc.html
@ArinaBallerina поделилась, как решала проблему генерации документации в PDF при использовании MkDocs, пробовала md2pdf, typora, foliant, голый pandoc. Ссылка на сообщение и последующий тред: https://t.me/docsascode/11631

12.12

У Gatsby есть стартер паки для быстрого поднятия под разные нужды, вот например для блога: там всё сводится к gatsby new gatsby-starter-blog https://github.com/gatsbyjs/gatsby-starter-blog

16.12

Обсуждали, кто как делал фидбек для документации. Варианты: можно использовать events в Google Analytics, подключить сторонний макрос, использовать typeform, создавать ишью в репозитории или Джире. @filhodejaneiro поделился ссылкой на туториал для SSG+GA https://www.docsy.dev/docs/adding-content/feedback/ Пример из Plesk: https://docs.plesk.com/en-US/obsidian/administrator-guide/about-plesk.70559/
@SirEdvin поделился ссылкой на release notes https://vector.dev/releases/0.6.0/, сделанные на Docusaurus 2 (https://github.com/timberio/vector/tree/master/website). Темная тема включается при соответствующей настройке в системе. параметр prefers-color-scheme. Ссылка на релиз новой версии Docusaurus: https://deploy-preview-2100--docusaurus-2.netlify.com

18.12

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

Ссылка на доклад Андрея Емельянова на мини-гипербатоне про lua-фильтры для pandoc: https://www.youtube.com/watch?v=LjB7C24EO5c
Команды переброса из rst формата в md для pandoc: https://gist.github.com/zaiste/77a946bbba73f5c4d33f3106a494e6cd
В бету вышла Windows Subsystem for Linux 2: https://devblogs.microsoft.com/commandline/wsl-2-is-now-available-in-windows-insiders/
Вопрос: есть легаси-документация в docbook xml, перегнал в md, теперь хочу в PDF. Ломаются сложные вложенные списки.
Как анализировать фидбек? Среднее время чтения, лайки vs дизлайки, хитмапы. Отсортировать статьи по среднему баллу, улучшать самые плохие.

20.12

@oplatonova задала вопрос про Markdown, можно ли в исходном файле md (который будет конвертирован в html) ввести дополнительные теги - например, указывать ключевые слова, которые будут конвертированы в вид <META Name="keywords" Content="keywor1, keyword2">. Ответы: https://www.markdownguide.org/extended-syntax/#definition-lists && or https://www.markdownguide.org/extended-syntax/#footnotes
pandoc может из YAML metadata block. Это не чистый markdown, конечно, но и не HTML внутри markdown, с помощью такого ключа можно добавить параметры title и keywords, которые экспортируются в HTML-документ, или записать тоже самое в YAML metadata block.
Можно ли в исходном файле tex. при конвертации в docx исключить из вывода некоторые блоки? Например, из блока \begin{ figure} и begin{tcolorbox} вывести figure. Можно написать фильтр (pandoc lua filters).

24.12

@nmpotashnikoff спросил, сталкивался ли кто-нибудь с проблемой сравнения двух текстовых pdf-ов с тем, чтобы на выходе был отчёт (текстовый или pdf’ский )? Варианты: попробовать https://helpx.adobe.com/acrobat/using/compare-documents.html, https://www.diffchecker.com/pdf-diff, http://www.qtrac.eu/diffpdf.html и http://www.linuxandubuntu.com/home/compare-pdf-files-with-diffpdf-in-ubuntu-linux-debian-fedora-other-derivatives, вот эту либу можно включить в CI https://www.inetsoftware.de/products/pdf-content-comparer.
Найденное решение (спасибо @SuckMyNuts): постраничный diff https://github.com/JoshData/pdf-diff, на выходе дает png.

30.12

Обзор HAT решений: https://www.indoition.com/online-help-authoring-tools-survey.htm