Перейти к содержанию

Ведение документации

Общая информация

Главным правилом является само по себе ведение документации (т.е. то, что её нужно вести). 😏

Вся документация ведётся непосредственно в git репозитории в виде .md файлов.
При пуше изменениий кодовой базы игры, одновременно должны пушится изменения в соответствующих статьях документации.

Для получения сайта из файлов статей используется статический генератор сайтов MkDocs.

Публичная и внутренняя документация

Сайт с документаций имеет две версии: публичный и полный (публичные разделы, плюс раздел внутренней документации).

В связи с этим, при ведении документации нужно помнить, что допускается делать ссылки из внутренней документации в публичные разделы, но не наоборот: ссылки из публичных разделов во внутренний не допускаются!

Публичная документация - это база знаний для игрока: какие есть сущности в игре, какие у них характеристики, как устроен геймплей. Также, там могут быть гайды, руководства и т.п.

Внутренняя документация - это техническая документация для команды разработки и различные правила.

Структура папки с документацией

Структура задана таким образом, чтобы из неё легко можно было автоматически получить статический сайт. А сайт является главным итогом, для которого она пишется.
Поэтому требуется неукоснительно, строго, безоговорочно и абсолютно точно соблюдать установленную структуру при ведении документации.

В структуру сразу заложена мультиязычность для сайта. 😎

Общая схема

  docs/
  │
  ├── articles/                                # Папка исходников статей
  │  │
  │  ├── index.md                              # Главная страница
  │  ├── index.en.md                           # Главная на английском
  │  │
  │  └── 01-some-section/                      # Раздел документации
  │  │   ├── 001-some-article.md               # Статья
  │  │   ├── 001-some-article.en.md            # Статья на английском
  │  │   └── _attachments/                     # Все вложения раздела
  │  │      ├── some-pic.png
  │  │      └── some-pic.en.png 
  │  │ 
  │  └── _assets/                              # Стили, иконоки и т.п.
  │
  └── site/                                    # Папка для сборки сайта
    │
    ├── config/
    │  ├── mkdocs.template.yml                 # Шаблон конфига MkDocs
    │  └── requirements.txt                    # Список зависимостей
    │
    ├── ShadowCell.SiteBuilder/                # Проект сборки сайта
    │  ├── ShadowCell.SiteBuilder.csproj
    │  └── Program.cs 
    │
    └── build/
       ├── mkdocs.yml
       ├── public/
       └── full/

Папка исходников статей

Разделы документации - это папки. Сами статьи - это .md файлы.

В названии папок и файлов сначала должен идти индекс.
Это нужно для того, чтобы задавать порядок разделов и статей при автогенерации сайта по структуре.

Названия папок и файлов в итоге будут формировать путь к странице сайта. Поэтому, для каноничности, в названиях нужно использовать т.н. kebab-case:
разделение индекса и названия, а также слов в названии осуществляется через "-".

Разделы документации

Названия папок разделов должны нумероваться двузначными индексами (01, 02, и т.д.).

Допускаются вложенность разделов. У вложенных разделов индексация идёт по тому же принципу (индекс родительской папки никак не учитывается).

Файлы статей

Названия .md файлов со статьями должны нумероваться трёхзначными индексами (001, 002, и т.д.).

Файл должен содержать один H1 заголовок, который будет определять название статьи на сайте. Другие правила для содержания .md файлов можно посмотреть в файле настроек линтера (см. пункт config/).

В начале .md файла, перед заголовком, допускается использование YAML front matter.

Основной файл

Основным языком документации (по умолчанию) является русский.

Поэтому русскоязычный файл идёт без суффикса: 001-some-article.md

Файл перевода

Файлы с дополнительными языками должны лежать рядом с файлами основного языка и называться также, как файлы с основным языком, плюс суффикс соответствующего языка. Например:

  • русскоязычный файл 001-some-article.md
  • англоязычный файл 001-some-article.en.md

Какой-то магии 🧙‍♂️ в плане перевода не предусмотрено, поэтому в файле перевода должна находиться полная статья на английском языке.

Вложения

Все вложения в рамках одного раздела документации (одной папки со статьями) группируются в папку _attachments/

Если вложением, к примеру, является изображение, на котором есть русский текст, то для статьи на другом языке логично сделать отдельное изображение. В таком случае к наименованию изображения тоже нужно добавить индекс, т.е.:
some-pic.png и some-pic.en.png

Диаграммы и визуализация

Рекомендуемый стандарт: Mermaid

Для задач визуализации схем в проекте настоятельно рекомендуется использовать блоки с Mermaid внутри .md файлов, т.к. он без проблем отображается «из коробки» в большинстве редакторов и при генерации сайта MkDocs.

На Mermaid можно создавать:

  • Блок-схемы (Flowcharts): Логика механик, развилки в прокачке, условия покупки улучшений.
  • Диаграммы последовательности (Sequence Diagrams): Сетевое взаимодействие, обмен данными между клиентом, сервером и БД (например, процесс авторизации или отправка лога матча).
  • Диаграммы состояний (State Diagrams / State Machine): Поведение узлов защиты, смена фаз анимации, статусы подключения к лобби.
  • Диаграммы классов (Class Diagrams): Проектирование базовой архитектуры кода и связей между сущностями.
  • User Journey / Навигация: Архитектура игровых интерфейсов (UI Flow) — переходы между экранами меню и настроек.
Сложные диаграммы

Если возможностей Mermaid не хватает (например, нужна сложная кастомная графика, специфическая разметка UML или огромная ментальная карта на сотни узлов), можно использовать специализированные инструменты, например Draw.io или PlantUML (.puml).

Правила для сложных диаграмм:

  1. Исходники: Файлы проектов (.drawio, .puml) обязательно сохранить в репозитории в папку _attachments.
  2. SVG: Рядок сохранить диаграмму как векторный .svg (растровые форматы теряют четкость при масштабировании).
  3. Вставка в документ: Подключить схему в файл .md стандартным тегом изображения.

Папка для сборки сайта

config/

В директории docs/site/config/ хранятся конфиги:

  • requirements.txt - файл зависимостей python, подключает плагины для MkDocs;
  • mkdocs.template.yml - шаблон для файла конфигурации MkDocs;
  • .markdownlint.yaml - правила для линтера .md файлов со статьями.

Проект сборки сайта

Небольшой dotnet проект. Основное предназначение - создание файла конфигурации MkDocs из шаблона (т.е. редактирование шаблона mkdocs.template.yml в зависимости от переданных настроек и сохранение в mkdocs.yml).

Также, перед сборкой сайта он выполняет валидацию .md файлов со статьями согласно правил линтера.

build/

Содержит итоговый файл конфигурации mkdocs.yml, а также сборки сайтов - публичную версию (public/) и полную (full/).

Разумеется, в репозитории её не храним.

Генерация сайта

Нюансы оформления

Настройка отображения меню сайта

Меню сайта строится согласно заданной структуры папок и .md файлов, в алфавитном порядке. Именно поэтому, в названиях папок и файлов необходимо использовать индексы для определения порядка пунктов меню.

Сами названия статей, берутся из заголовка H1 внутри .md файла со статьёй.

Названия разделов со статьями по умолчанию берутся по названиям папок.
Однако, для пунктов меню сайта требуется более подходящие названия, чем к примеру "03-gameplay". Поэтому необходимо задавать человекочитаемые названия пунктов меню в файле шаблона конфигурации MkDocs docs/site/config/mkdocs.template.yml, в секции настроек плагина перевода:

  • в качестве ключа задается имя папки: 03 gameplay (символы - и _ заменяются пробелами);
  • в качестве значения задаётся нужное название для пункта меню: Геймплей или Gameplay (на языке, согласно заполняемого блока).

Может выглядеть запутанно, но если посмотреть файл шаблона, то должно стать понятней.

Таким образом, для меню сайта:

  • порядок статей задаётся структурой автоматически;
  • порядок разделов (секций) задаётся структурой автоматически;
  • названия статей задаются заголовками H1 автоматически;
  • названия разделов (секций) задаются в файле шаблона MkDocs вручную.

Дополнительные возможности форматирования

Текст в рамках

Для заключения текста в рамку с иконками (информация, внимание и т.п.), возможно использовать следующее форматирование:

Текст на сером фоне, в серой рамке, с голубым значком информации

Текст на синем фоне, в красной рамке, с синим значком карандаша

Текст на красном фоне, в красной рамке, с красным значком молнии

В редакторах md файлов, к сожалению, рамки не отрисуются. Однако на сайте это будет выглядеть аккуратно.

Консольные команды

Команда установки зависимостей MkDocs

Из корня решения: pip install -r docs/site/config/requirements.txt

Команды сборки и запуска документации

Все примеры команд даны для запуска из корня решения.

Общий формат
dotnet run --project docs/site/ShadowCell.SiteBuilder -- <команда> <режим> [опции]

где:

  • <команда>
  • serve — запускает локальный веб-сервер документации.
  • build — собирает статическую версию документации.
  • <режим>
  • public — только публичная версия документации.
  • full — полная версия документации.
  • [опции]
  • --no-lint — отключает проверку линтера во время сборки или запуска.
Примеры
Запуск локального сервера
dotnet run --project docs/site/ShadowCell.SiteBuilder -- serve public
dotnet run --project docs/site/ShadowCell.SiteBuilder -- serve full
Сборка статической документации
dotnet run --project docs/site/ShadowCell.SiteBuilder -- build public
dotnet run --project docs/site/ShadowCell.SiteBuilder -- build full
Запуск без проверки линтера
dotnet run --project docs/site/ShadowCell.SiteBuilder -- serve public --no-lint
dotnet run --project docs/site/ShadowCell.SiteBuilder -- serve full --no-lint
Сборка без проверки линтера
dotnet run --project docs/site/ShadowCell.SiteBuilder -- build public --no-lint
dotnet run --project docs/site/ShadowCell.SiteBuilder -- build full --no-lint

Рекомендуемые инструменты

Для написания статей документации рекомендуется использовать Obsidian.

Причины:

  • удобное форматирование текста;
  • простая работа с вложениями;
  • корректная работа со ссылками между статьями;
  • автоматическое обновление ссылок при переименовании файлов;
  • навигация по структуре документации;
  • граф связей между статьями.

Конечно, возможно использование и других редакторов. Редактировать статьи, может быть даже удобней прямо в IDE, т.к. сразу видны изменения git.

В любом случае автор изменений обязан убедиться, что:

  • структура каталогов не нарушена;
  • ссылки между статьями корректны;
  • вложения размещены в папке _attachments в папке раздела со статьёй;
  • документация корректно отображается на сайте, полученном MkDocs (и линтер не ругается).

Первичная настройка Obsidian

Шаг 1

  • Открыть Obsidian.
  • Выбрать Open folder as vault
  • Указать папку docs/articles/ в репозитории игры

Шаг 2

Настроить вложения

Settings → Files and links
Default location for new attachments

Выбрать In subfolder under current folder
Название папки: _attachments

Теперь при вставке картинки, Obsidian автоматически создаст папку и положит файл туда.

Шаг 3

Настроить ссылки

Settings → Files and links
New link format

Поставить Relative path to file

Шаг 4

Включить полезные стандартные плагины

Settings → Core plugins

  • Backlinks
  • Page Preview
  • File Recovery
  • Outline (оглавление статьи по заголовкам)