Документирование

Источники

Помимо текущей документации, часть знаний описана в файлах doc.go внутри некоторых пакетов.

Также часть знаний отражена в комментариях к структурам, методам, константам и переменным.

Несмотря на спорный статус принципа "само-документирующийся код", все используемые в проекте термины и наименования призваны наиболее явно и непротиворечиво выразить суть того, чему они присвоены.

Как написана текущая документация?

Используется Material for MkDocs.

Документация состоит из набора *.md файлов формата Markdown в каталоге ./docs/ текущего сервиса.

Структура документации описана в конфигурационном файле mkdocs.yml.

Для запуска локального сервера с моментально обновляемым предпросмотром документации используется команда:

docs-serve

Собранная документация к сервису расположена на отдельном URL-е и представляет собой контейнер, который рендерит статические файлы.

Для сборки такого контейнера и отправки его в Docker Registry staging-окружения используется команда:

docs-push