Документация¶

README.md¶

В репозитории в корне должен находиться файл README.md, в котором указаны:

Краткое описание проекта
Требования к окружению для разработки
How to build: описание, как собрать проект
Cake: если используется автоматизированная система сборки, должно быть описание команд
CI: если настроен CI, должно быть описание этапов
Структура проекта: краткая описание структуры репозитория

Документация к проекту должна находится в том же репозитории, что и сам код, в каталоге docs. Структура каталога следующая:

-docs
|- images
|-- App1
|-- App2
|- App1
|- App2
|- schemas
|-- App1
|-- App2

В images помещаются все изображения, которые есть в документации, в schemas - схема, диаграммы. Схемы выполняются в draw.io, исходники схем хранятся вместе с кодом для версионирования. В указанных каталогах нужно также создавать подкаталоги для каждого приложения или сборки. Для сборок и приложений возможно группировка в подкаталоги.

Дальнешие пункты требуют обсуждения и актуализации [15.02.2021]

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

index.md: общая информация о приложении или сборке
requirements.md: требования к системе для запуска приложения (версия framework, OS, наличие других сервисов, БД и прочего)
configs.md: подробное описание параметров приложения, на что влияют, примеры
install.md: описание процесса установки, конфиги установки (nginx, systemd, пример NLog.config для production)
update.md: описание процесса обновления (опционально)

Также будут полезные следующие опциональные файлы в подкаталоге optional:

limitations.md: ограничения работы приложения (при каких данных не будет работать, ограничения по памяти и т.д.)
architecture.md: описание архитектуры
любые другие полезные статьи

В корне docs могут находиться различные статьи, которые относятся к работе системы в целом (архитектура, взаимодействие систем, use-case'ы, описание работы для пользователя и т.д.).

Генерация документация в виде сайта¶

На основе md файлов с помощью mkdocs разворачивается статический сайт с документацией.

Важно. Сайт статический. Авторизации нет. Нельзя выкладывать чувствительную информацию. Но можно обойти, если в nginx настроить ограничение доступа по ip (пример тут).

mkdocs¶

Установка¶

Ниже описана установка на Linux системы, т.к. сборка проходит на этих серверах.

Если есть желание работать на Windows, можно дополнительно описать установку на него в этой статье.

Для создания сайта нужно:

Установить python (обычно уже установлен);
Установить pip (how to)

Важно. Для корректной работы mkdocs нужен python версии 3 и выше. pip тоже нужен 3 версии.
Установить mkdocs:

sudo pip3 install mkdocs

Установить темы. Например, для U-CATI выполнить:

sudo pip3 install mkdocs-material

Установить дополнительные плагины. Например, для организации вложенных файлов необходимо поставить

sudo pip3 install markdown-include

mkdocs для своей работы использует файл mkdocs.yml. К сожаления, mkdocs не позволяет указать путь к файлу, а требует, чтобы команда выполнялась в той же директории, в которой есть файл (предполагается, что один репозиторй - один сайт документации). Для создания нескольких сайтов с документацией из одного репозитории (например, в проекте U-CATI для менеджеров и исполнителей) приходится идти на ухищрения, а именно создавать еще один каталог docs, потому что файл конфигурации не может лежать в той же директории, где и файлы документации.

Создание сайта¶

Для создания сайта нужно выполнить команду:

mkdocs build --clean

Можно развернуть его локально для тестирования:

mkdocs serve

Можно в файле mkdocs.yml указать параметр dev_addr: ip:port, по которому команда server будет разворачивать документацию.

mkdocs позволяет использовать различные темы для оформления сайта. Мы используем mkdocs-material.

Поиск¶

Сайт поддерживает поиск статей. Т.к. сайт статический и у него нет backend'а, то для поиска при генерации создаются индексы. По умолчанию они создаются только на английском языке. Чтобы включить поиск на русском нужно в файл конфигурации добавить следующие параметры:

plugins:
    - search:
          lang: 
              - 'en'
              - 'ru'

Отдельные темы используют свой поисковый движок. Для поиска при использовании темы material нужно в конфиг добавить следующее:

extra:
  search:
    language: 'en, ru'

Вложенные файлы¶

Может возникнуть ситуация, когда в документации для разных пользователей есть как повторяющая часть, так уникальная. Общую часть можно вынести в общий файл, который потом можно "включить" в уникальный. Например, в описании работы с проектом есть общая часть, которая будет полезна всем пользователям, и инструкции по изменению статуса проекта, которая должна быть доступна только менеджеру. Общую часть выносим в common, а для менеджера создаем отдельный файл, в котором нужно указать следующую инструкцию:

````

Чтобы все это работало, нужно установить отдельный инструмент для препроцессинга md файлов - `markdown-include` (описано выше).


После в файл конфигурации нужно добавить следующие строки:

```yaml

markdown_extensions:
    - markdown_include.include:
          base_path: docs

Общая документация¶

Чтобы не дублировать текст нужно общую часть размещать в common и делать символьные ссылки на эти файлы в каталогах manager и contractor (обязательно символьную ссылку, чтобы все работало на разных машинах). Делать это нужно через консоль:

ln -s ../../common/profile.md ./misc/profile.md

Важно указывать относительный путь, а не абсолютный.

Ссылки создавать обязательно, чтобы в самих md файлах можно было делать ссылки на другие страницы документации.

Изображения¶

Изображения также должны храниться в каталоге docs, который будет публиковаться как сайт. Чтобы не дублировать изображения также необходимо делать символьные ссылки. Общие изображение также нужно размещать в каталоге common/images.

Полезные ссылки¶

Различные полезные ссылки по созданию документации: