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

Правила работы с документацией Planiqum

Примечание: Этот документ предназначен для разработчиков и содержит правила работы с документацией Planiqum.

Важное правило

  • Все новые статьи должны быть добавлены в оглавление соответствующего раздела документации (например, dev.md или admin.md), а также в nav секцию mkdocs.yml для отображения в меню документации.
  • Не допускается создание документации, которая остаётся без ссылок ("повисает в воздухе").
  • При добавлении новой статьи обязательно добавьте ссылку на неё в оглавление и/или навигацию, а также в nav секцию mkdocs.yml.

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

Документация размещена в директории src/planiqum/docs и разделена на следующие основные разделы:

  1. md/admin/ - документация для пользователей
  2. Содержит инструкции по работе с системой
  3. Описывает функциональность с точки зрения конечного пользователя

  4. Включает разделы: параметры, иерархии, конвертации, дашборды и т.д.

  5. md/dev/ - документация для разработчиков

  6. Содержит техническую документацию
  7. Описывает архитектуру и API

  8. Включает разделы: базовые концепции, отчеты, AWS и т.д.

  9. md/release_notes/ - заметки о релизах

  10. Содержит информацию об изменениях в версиях
  11. Описывает новые функции и исправления

Структура разделов и организация навигации

  • Для каждого крупного раздела документации создаётся отдельная директория (например, admin/parameters, dev/reports и т.д.).
  • В каждой директории раздела обязательно должен быть файл index.md, который служит статьёй "Введение" для этого раздела.
  • В файле index.md:
  • Кратко описывается, о чём этот раздел.
  • Приводятся ссылки на все остальные статьи раздела с короткими комментариями (ручная мини-навигация).
  • "Введение" всегда идёт первым пунктом в разделе (и в mkdocs.yml).
  • Все новые статьи раздела размещаются в этой же директории и добавляются в навигацию через mkdocs.yml.
  • Внутренние ссылки между статьями раздела должны быть относительными (например, [Импорт данных](import_data.md)).

Оформление якорей для подзаголовков

  • Каждый подзаголовок снабжается явным HTML-якорем на английском языке, например: <a id="import-errors"></a> ## Обработка ошибок
  • Для ссылок на разделы и подразделы использовать только такие якоря (не автогенерируемые кириллические).
  • Якоря должны быть короткими, осмысленными, без пробелов и спецсимволов.

Правила оформления ссылок

  1. Для внутренних ссылок между статьями раздела использовать относительные пути: [Название](article.md) или [Название](subdir/article.md).
  2. Для ссылок между разделами — относительный путь от текущего файла: [Параметры](../parameters/index.md).
  3. Для ссылок на якоря — [Подробнее](#anchor-name) или [Подробнее](article.md#anchor-name).
  4. Не использовать абсолютные пути с /core/docs/web/... для внутренних ссылок — это усложняет поддержку и переносимость.
  5. Для внешних ресурсов — всегда указывать полный URL.

Правила размещения файлов

  1. Новые файлы документации должны размещаться в соответствующем разделе:
  2. Пользовательская документация → md/admin/
  3. Техническая документация → md/dev/

  4. Заметки о релизах → md/release_notes/

  5. Именование файлов:

  6. Использовать нижний регистр
  7. Разделять слова дефисами
  8. Использовать расширение .md
  9. Пример: basic_concepts.md, report_data.md

Правила форматирования

  1. Заголовки:
  2. Использовать Markdown-синтаксис (# для заголовков)
  3. Начинать документ с заголовка первого уровня (#)

  4. Использовать иерархию заголовков (#, ##, ###)

  5. Ссылки на изображения:

  6. Размещать в директории md/images/
  7. Использовать относительные пути

  8. Пример: ../images/admin/conversions/currencies-example.png

  9. Код:

  10. Использовать блоки кода с указанием языка
  11. Пример: ```python для Python-кода

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

  1. После внесения изменений в документацию необходимо:
  2. Пересобрать документацию командой python src/planiqum/docs/build_docs.py
  3. Проверить корректность ссылок

  4. Убедиться, что все якоря работают

  5. При добавлении новых разделов:

  6. Создать соответствующие файлы в правильных директориях
  7. Добавить ссылки на новые разделы в навигацию
  8. Обновить перекрестные ссылки в существующих документах

Взаимодействие между разделами

  1. Пользовательская документация (admin/):
  2. Должна содержать ссылки на соответствующие разделы разработческой документации
  3. Использовать простой язык, понятный конечным пользователям

  4. Включать примеры и скриншоты

  5. Разработческая документация (dev/):

  6. Должна содержать технические детали
  7. Включать примеры кода
  8. Ссылаться на соответствующие разделы пользовательской документации

Проверка документации

  1. Перед публикацией необходимо проверить:
  2. Корректность всех ссылок
  3. Работу якорей
  4. Форматирование текста
  5. Наличие всех необходимых изображений

  6. Соответствие правилам именования файлов

  7. После публикации:

  8. Убедиться, что документация доступна по правильным URL
  9. Проверить работу навигации
  10. Протестировать все ссылки

Назначение файла index.md

  • В корне всей документации (src/planiqum/docs/md/index.md) файл index.md используется только как главная страница документации (приветствие).
  • В директории раздела (например, admin/parameters/index.md) файл index.md используется как статья "Введение" для этого раздела.
  • В разделе "Введение" допустимо размещать краткое описание раздела и ссылки на остальные статьи раздела с комментариями (ручная мини-навигация).
  • "Введение" всегда идёт первым пунктом в разделе (и в mkdocs.yml).
  • Навигация по разделам и добавление новых статей осуществляется только через секцию nav файла mkdocs.yml.

Формат ссылок на код

При оформлении документации и промптов для AI-ассистента используйте следующий стандарт ссылок на код:

  • Ссылка на файл: Абсолютный путь от корня репозитория, начиная с /.

  • Пример: /src/planiqum/core/filters/tests/test_fact_filtering.py

  • Ссылка на класс или функцию внутри файла: Абсолютный путь к файлу с добавлением # и имени класса или функции.

  • Пример для класса: /src/planiqum/core/filters/libs/filter.py#Filter

  • Пример для функции: /src/planiqum/core/filters/libs/data_request.py#apply_to_query

  • Не используйте ссылки с ::, относительные пути (../../), либо другие нестандартные форматы.

  • Такие ссылки должны быть кликабельны и корректно работать в IDE Cursor и markdown-документации проекта.

Пример использования в тексте:

Подробные тесты фильтрации см. в файле [/src/planiqum/core/filters/tests/test_fact_filtering.py]. Реализация класса фильтра — [/src/planiqum/core/filters/libs/filter.py#Filter].

Минималистичный формат для ссылок на класс или функцию

Для ссылок на класс или функцию внутри файла используйте формат:

  • /путь/к/файлу.py: ИмяКласса
  • /путь/к/файлу.py: имя_функции

Примеры: - /src/planiqum/core/filters/libs/filter.py: Filter - /src/planiqum/core/filters/libs/data_request.py: apply_to_query

Такой формат минималистичен, однозначен и легко читается. Даже если IDE не поддерживает переход по такой ссылке, читатель всегда поймёт, где искать нужный объект. Этот формат рекомендуется использовать во всей проектной документации для ссылок на классы и функции.

Требование к тексту ссылки

Текст ссылки в markdown должен полностью повторять путь (и имя класса/функции, если указано после двоеточия). Это обеспечивает однозначность даже при копировании ссылки без форматирования.

Пример оформления markdown-ссылки:

[/src/planiqum/core/filters/libs/filter.py: Filter](/src/planiqum/core/filters/libs/filter.py)

или для файла:

[/src/planiqum/core/filters/tests/test_fact_filtering.py](/src/planiqum/core/filters/tests/test_fact_filtering.py)

Таким образом, даже если ссылка скопирована как текст, всегда понятно, куда она ведёт.