Примечание. Начинаю писать статьи, поэтому будем признательны за любые отзывы.
Введение
Управление технической документацией — это Haaaard. Все будут его писать, но никто не будет его поддерживать. Confluence, Readme, Gitbook, Read the Docs и т. д. и т. д. служат прекрасной цели, однако, если вам действительно нужна самая последняя документация для ваших систем и отделов, давайте начнем прямо сейчас!
› Если у вас нет времени читать, то вы можете просмотреть результаты [здесь]
› Или, если вы просто хотите получить исходный код с учебным пособием, посетите [github repo]
Что это такое?
docker + Mkdocs + плагины Mkdocs + draw.io + mermaid + meta
Тогда покажи мне
Установить репозиторий
git clone [email protected]:cribmove/mkdocs-example-demo.git cd mkdocs-example.demo cd docs docker compose up -d
Посетите http://localhost:8124
Хорошо, но что еще?
Несколько репозиториев
Просто используя такой инструмент, как https://www.npmjs.com/package/meta, вы можете собрать множество репозиториев в центральный репозиторий = отлично подходит для наблюдения за несколькими проектами и *централизации* документации. Все, что вам нужно сделать, это подключить внешний репозиторий mkdocs.yaml, как показано ниже:
nav: — External Repository: ‘*include ./second-repo/mkdocs.yml’
Интеграция Draw io
Используя расширение VSCode draw.io, вы можете создавать диаграммы в редакторе кода и просматривать их в своих MKdocs!
Русалка
Если у вас есть аппетит к этому, вы можете сделать диаграмму в коде, используя синтаксис [mermaid](https://mermaid-js.github.io/mermaid/#/). Хотя существует кривая обучения, преимущества построения диаграмм рядом с вашим кодом перевешивают время обучения.
Интеграция с открытым API
Если вы придерживаетесь своей спецификации и определений API, вы можете опубликовать свои локальные определения в своей документации (опять же полезно для полирепозиториев и контрактов).
Заключение
Mkdocs не для всех, но он удовлетворяет требованиям разработчиков. Расширяемость, история git и быстрый доступ, которые дает вам Mkdocs, действительно сделают ваш опыт разработки более приятным. Вы можете не только быстро создавать, но и легко публиковать на страницах Github, в облаке и Netlify!
Попробуй!