Апрель в DocOps чате

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

Мониторинг сайтов с документацией

Настройка оглавления и переменных в Sphinx

Выбор решения для деплоя и хостинга сайта с документацией

Построение майндмэпов из маркдауна

Деплой сайта без кода

Автоматическая съемка и публикация скриншотов

Проверка сломанных ссылок

У Zeit поменялись цены и условия

Упомянутые инструменты: Grafana, Sphinx, markmap-li, Netlify, Zeit, Cypress, Hugo, Jekyll, brok, muffet,

01.04

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

• Prometheum/Grafana/ELK
• @Stanislav_techwriter поделился статьей, как прикрутить мониторинг: https://docs.google.com/document/d/1-erjOtICSP-NGOvY6b1SZec3jV0zvMZNbTQdgSnD_aE/edit?usp=sharing
• @maxlapshin предложил прикрутить яндексметрику, она будет сообщать об отвале хостинга.

04.04

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

Не попадались ли кому-нибудь инструменты, позволяющие это реализовать?

• В Sphinx в rst_epilog
• Попробовал, подстановки типа |variable| не подходят для .. include::, видимо подстановка происходит после того, как Sphinx пытается получить путь до файла

06.04

Подскажите как в sphinx сформировать toctree так, чтобы описание модуля 2 было подпунктом в дереве навигации модуля 1? Если наглядно, то как сделать "Geoserver" подпунктом "Установка дополнительного ПО"?

• можно убрать его из общего toc и сделать локальный toc внутри страницы установка дополнительного по на сервере

11.04

Коллеги, кто-то сталкивался с документированием по теме блокчейнов и прочей дребедени?

• @SenyaChe у меня знакомый работает, больше всего задач по подготовке пакетов документов для сертификации по безопасности
• @exebeeche работаю больше года в блокчейн-компании, полёт нормальный, всё как в любой айтишной компании, одни и те же языки программирования, те же принципы работы, своя специфика, может, посложнее, чем в большинстве компаний, наверное, ближе к финтеху

13.04

Ищу заклинателей swagger2marup и asciidoc

• Разработчики баловались swagger2markup. Потом пришел новый senior и все перешли на Spring REST Docs и Spring MVC Test. в итоге на выходе я теперь получаю html вместо swagger. И в MkDocs этот html довольно симпатично отображается
• @nmpotashnikoff: swagger2markup не поддерживает Open API 3. Мы пользуемся вот этим проектом https://github.com/openapi-contrib/openapi3-generator На выходе имеем asciidoc, причем размеченный тэгами. Т.е. в конечную документацию я могу вставлять не сгенерированные файлы а то из них, что нужно. А дальше — html... pdf... jekyll... все. что душе угодно. Нужны только npm и OpenAPI 3 Generator

14.04

а кто-нибудь встраивал сваггер в статику с md?

• @ivan_cheban https://enigma.com/blog/post/integrating-autogenerated-content-into-your-documentation-site-using-swagger-and-jekyll?d=1

17.04

обычный контрдовод относительно SSG такой: поддерживать сайт на CMS-ке сможет любой контент-менеджер без глубокого айтишного бэкграунда, а для SSG нужно и в гит уметь, и в верстку чуть-чуть

как вы это решили?

• по факту это не так. Такому менеджеру рядом нужен ещё девелопер, который сбекапит мускль, поправит настройки.
• Отвечая на вопрос: у меня сайт правит менеджер сайта (по сути он больше про SEO) и техпис. Оба могут что-то пойти сделать или хотя бы внятно сказать «ой, у нас всё сломалось, помогите».

А Netlify вы не рассматриваете для деплоя? Я уже пробовал GitHub Pages, GitLab Pages. Мне больше всего понравился Netlify. Я ещё не пробовал S3.

• @nineteeneyes Есть очень интересное решение от ребят из Zeit. Они же авторы Next.js и остальных толковых вещей. https://zeit.co
• Опробовал Zeit. Отличная штука! В несколько тапов с мобильного задеплоил мои эксперименты на Джекилле. Очень быстро билдит, минуту.

18.04

@olegkovalov поделился ссылкой на сервис, который строит майндмапы из маркдауна markmap-lib: https://markmap.js.org/repl/

19.04

А как называется процесс проверки, что перекрёстные ссылки в документации ведут туда, куда надо, и не делают 404?

• broken links linter/checker
• @factorized: Аккурат сегодня на HN проскакивала маленькая утилитка для этого, https://github.com/smallhadroncollider/brok
• @maxlapshin: Я только что ее через ruby gem mechanize сделал, чтобы провалидировать, как ссылки переехали с сайта на сайт
• попробовал brok, но он не умеет во внутренние (относительные) ссылки
• попробовал muffet, но мне всё таки хочется запускать эту штуку перед деплоем (на папке, а не на сайте), а не только по крону
• Попробуйте https://github.com/gjtorikian/html-proofer
• Не сталкивались что на некоторые URL-ы 100% валидные выкидывает timeout?Из самых заметных примеров: http://techradar.avito.ru/, другие чекеры вроде его съедают нормально.

21.04

Неожиданно Zeit стал Vercel: https://zeit.co Новости об изменениях в платформе: https://m.youtube.com/watch?v=WaxRMqh_cK0

Поменялись цены и условия.

24.04

@ivan_cheban: Netlify гораздо быстрее, чем Zeit (Vercel) деплоит изменения на статическом сайте в Джекилле. По крайней мере, если комитишь из фористри. 1 минуту — нетлифай, 3 минуты — Vercel.

26.04

@maxlapshin Хотел поделиться: мы в флюссонике начали имплементить такую идею, чтобы склеить тесты и документацию.

В документации полно примеров кода, которые непонятно кто и как проверял. Есть скриншоты и видео, которые делались техписом вручную. Техпис настраивал софт, кликал мышкой, т.е делал ту же работу, которую делает тестировщик. Хочется максимально заменить ручную работу на автоматическую.

Мы хотим положить рядом с документацией тесты, которые будут шарить какие-то сниппеты между генерируемой документацией и кусками тестов/конфигов/т.п. Сейчас как раз сделали первые шаги, позволяющие вынести все куски конфига в отдельные сниппеты и убедиться, что хоть где-то в тестах они были включены.

Реализация: Тест на Cypress, который делает то же самое, что и техпис. Но в нужный момент делает скриншот

как вам идея вообще обойтись без кода, чтобы задеплоить сайт? Вот человек рассказывает и показывает, как это сделать: https://geshan.com.np/blog/2020/04/jamstack-tutorial-website-with-no-code-for-free/#steps

28.04

@ivan_cheban: Нашел интересный сайт со статистикой по разным технологиям, включая SSG: https://www.wappalyzer.com/technologies/static-site-generator

30.04

Коллеги, такой вопрос - какие лицензии используются для распространения справочного контента? Может, кто-то использует какие-либо лицензии GNU на документацию, как это вообще выглядит

• @b0g3r Мы в tlroadmap используем CC-BY 4