Чтобы собрать документацию локально на текущей ветке/теге:
-
Перейдите на ветку/тег и инициализируйте python-окружение:
git checkout <branch/tag> cd documentation python3 -m venv venv source venv/bin/activate pip install -r requirements.txt
-
Соберите или запустите сайт:
mkdocs build
mkdocs serve
На данный момент документация поддерживает два языка:
- Русский 🇷🇺 - по умолчанию
- Английский 🇺🇸
Раздел - группа страниц, описывающая одну конкретную тему. Раздел может включать подразделы.
Раздел оформаляется в отдельной директории. Каждый раздел обязан иметь страницу с именем index.md,
в которой описывается тематика раздела.
Страница - страница с произвольным именем и расширением .md, написанная на markdown.
При добавлении страницы и раздела, добавьте их в секцию nav в файле mkdocs.yml:
Пример раздела:
Пример оформленной навигации для этого раздела:
Документация поддерживает рендеринг plantuml-диаграмм. Для того чтобы добавить схему plantuml в
текст страницы markdown используйте блок кода с расширением puml:
```puml
@startuml
Alice -> Bob: test
@enduml
```
Документация поддерживает отображение схем, написанных в drawio (файлы с расширением .drawio).
Необходимо добавить схему в директорию assets. В тексте markdown добавьте схему также как
добавляете обыное изображение, используя относительный путь:
Документация поддерживает добавление в текст markdown включение текста из других файлов (snippets).
Для того, чтобы добавить snippet в текст markdown изучите
документацию расширения.
Путь к файлам, которые будут включены вычисляется относительно директории
docs/documentation/examples.
Также поддерживаются следующие дополнения:
- Использование emoji в тексте страниц.
- Табы
- Сноски
- Диаграммы mermaid
- Admonitions
- Аннотации