Comments 18
Почему именно MkDocs, а не Docusaurus или VitePress?
А почему не reStructuredText?
MkDocs — это просто. Markdown + YAML, без JS/React/Vue. Из коробки работает с GitHub Pages, быстрая сборка, Material for MkDocs — шикарная тема. Если нужна документация, а не мини-SPA с компонентами — MkDocs идеален.
А почему не reStructuredText? Потому что reST — боль (хотя да не для всех). Сложный синтаксис, трудно читать, трудно писать. Markdown стал стандартом, и он везде.
По моим ощущения rst как раз спасение от боли нестандартизированного markdown. Markdown - это даже не формат, а куча диалектов, Mkdocs вводит свои расширения. Кроссдокументные ссылки, например, мне не понравились как там сделаны.
Да, rst своеобразный формат, но когда я пытался делать документацию для своего проекта на mkdocs, я быстро сдался и решил потратить время на изучение rst и он оказался не таким уж сложным
В связи с этим хотелось бы понять, было ли какое-то объективное сранение или вы как и я выбрали просто что показалось приятнее в использовании?
Тогда уж не RST a Sphinx (который умеет и Markdown тоже)
А почему не Backstage?
Потому что это уже не "документация", а целый портал)
Backstage — это как CMS + DevOps-панель + каталог микросервисов. Чтобы его поднять, нужен как минимум Kubernetes-энтузиазм и свободный вечер. MkDocs про, простенькую статичную доку.
Так показывать md документы и OpenAPI умеет gitlab, прямо рядом с кодом. Зачем тогда городить mkdocs? А если делать, то уже хорошо.
ПС понимаю, что фломастеры у всех свои, но имхо ваше решение из разряда "потому что могу".
MkDocs — это как сделать из документации удобный сайт с меню, поиском и приятным дизайном. Людям так проще ориентироваться и искать нужное. Короче, если документация только для своих — GitLab сойдёт (и даже хороший вариант). Если хочешь, чтобы её реально читали и понимали — лучше сделать сайт, типа MkDocs. Просто и понятно.
чтобы её реально читали и понимали
Не понял почему документация в Gitlab / Github не подходит для этого
лучше сделать сайт
В базовом варианте Backstage как раз просто сайт генерирует под каждый найденную репку (не знаю где вы там нашли "CMS+DevOps панель+микросервисы"). Плюс умеет все неплохо структурировать и строить поиск. И как раз поверх mkdocs с АВТОМАТИЧЕСКИМ обновление после каждого коммита в репку. Итого у вас одна точка входа в проект (в дополнение к git).
У нас, например, Github непубличный, а просить каких-нибудь продажников в нём регистрироваться чтобы дать доступ - странное решение. В Github у нас сейчас 120 репозиториев и тащить все доки из них всех нам не нужно, проще всё собрать в одном месте. Wiki из github мне лично кажется совершенно неудобным и не настраиваемым. Возможно, в gitlab оно всё как-то и лучше, но сейчас мы на него переезжать не будем точно, так что я даже сравнивать не пойду.
MkDocs поднят в контейнере на сервере во внутренней сети за VPN. Все пользователи с VPN могут иметь доступ. Кажется, даже дополнительно авторизуются через SSO, но сейчас не помню. Если нужно будет что-то разграничить - придётся придумывать ещё варианты (или искать плагины).
Заметьте - я с вами совершенно не спорю, а описываю отдельный случай когда github не является лучшим местом для доков. Ваше предложение вполне рабочее для другого случая.
Если хватает базового Markdown - то можно и в gitlab.
Но обычно всегда хочется чего-то ещё. Вот пример из официальной документации FastAPI.
Вот есть, например, такие табы для кода или заметок. Удобно - да. Нужно ли - ну не всегда.
Есть плагины для сворачивания части текста или выделения каких-то блоков отдельным цветом/заголовком (см в той же документации на страницу ниже). Удобно - да. Нужно ли - не всегда.
В целом, я поддержу статью, хотя это решение вполне может подойти не всем.
Я тоже выбрал MkDocs для внутренней документации, но у меня совсем маленькая команда - 2-4 человека.
Markdown - отдельные файлы, просто версионируются в репозитории. Если вам, например, нужно на странице видеть историю правок - можно, конечно, приделать интеграцию с git, но, наверное, лучше не нужно и лучше смотреть на тот же Confuence.
Простой синтаксис Markdown стимулирует рисовать простые странички, без таблиц третьей степени вложенности и прочих сложных элементов. Плагины есть для всего, но, опять же, если хочется чего-то сложнее - лучше рассмотреть более сложные движки. Стили можно настраивать и html вставлять, в общем-то.
Плагинов реально дофига, и поначалу глаза просто разбегаются, хочется попробовать половину из них. Другой вопрос - насколько часто они обновляются. Ну это как любой опенсорс.
Confluence, например, тоже настраивается, но сложнее и дорого. Atlassian хочет чтобы всё было у них в облаке. Например, в онлайн-редакторе Jira постоянно вылезают какие-то баннеры и подсказки, что реально раздражает. И внешний вид настроить под себя довольно сложно, не говоря уж о том чтобы синтаксис MD немного расширить..
А есть смысл развернуть все это в Docker?
На мой взгляд - всегда есть смысл развернуть что-то в Docker. Особенно на фоне борьбы автора с virtualenv и прочими пакетами - статья была бы немного короче, если дать ссылку на официальный Dockerfile.
Правда, нужно учитывать, что ваши .md-файлики именно транслируются в html, а Dockerfile настроен на то, что он запускает development-сервер, который будет эти файлики раздавать, но и на лету конвертировать только что изменённые. Возможно, лучше будет в докере просто один раз их собирать в html и раздавать через nginx как автор.
Для себя и своей команды использую https://habr.com/ru/companies/gram_ax/articles/910716/ - в редакторе создаю статьи (как в word), которые под капотом являются md файлами (плюс их теги навигации). Из редактора изменения пушатся в Gitea, а из нее данные каждые 5 мин забирает (pull) докер контейнер с их докпорталом (веб сервер + конвертилка md->html). Все легко, быстро и красиво. Из настроек всего два yaml файла (Gitea и DocPortal) для docker compose и первичная настройка доступа к git по токену.
Из недостатков - продукт новый, встречаются ошибки, но ребята довольно быстро все фиксят.
Подскажите пожалуйста, какие есть инструменты/способы для автоматической конвертации документации из MD в PDF на примере вашей архитектуры?
Т.к. MD файлы в итоге становятся html, то проще с нормальными стилями конвертировать именно html в pdf. Для этих целей вполне неплох Weasyprint, умеет подключаемый css, автоматизацию можно сделать простым python скриптом который будет вызываться по нужному триггеру: https://doc.courtbouillon.org/weasyprint/stable/
Как мы подняли современный портал документации из россыпи .md файлов: пошаговое руководство по MkDocs + Material