Python Repository Documentation

Python Repository Documentation

Quick Start

1. Определи цель документации: API-контракт, архитектурный обзор, поведение модуля или публичного метода.
2. Задокументируй только факты, которые неочевидны из имени, типов и структуры.
3. Для публичных сущностей в ключевых слоях добавляй docstring минимум в краткой форме.
4. Пиши docstring на русском языке, коротко и без шаблонных формулировок.
5. Секции Args, Raises, Returns добавляй только при реальной необходимости.
6. Поддерживай README.md подробным по сути, но компактным по объему: чтение за пару минут или быстрее.
7. При изменении конфигурации применяй специализированный скил конфигурации приложения; в README оставляй только способ настройки и ссылки на примеры.
8. При изменении кода синхронизируй документацию в тех же файлах.

Documentation Rules

1. Docstring Language and Style

• Пиши docstring на русском языке.
• Базовый формат: одна короткая строка с сутью поведения.
• Избегай шаблонов вроде "Выполняет операцию...".
• Не дублируй аннотации типов текстом без добавленной ценности.

2. Required and Optional Sections

• Args: добавляй только для неочевидных параметров, ограничений или форматов.
• Raises: добавляй только для ожидаемых контрактных исключений.
• Returns: добавляй только если результат неочевиден.
• Для __init__ используй только релевантные секции.

3. Public vs Private

• Для публичных методов в domain, application, ports, presentation docstring обязателен.
• Для приватных методов docstring можно опустить, если поведение очевидно.

4. Architecture-Level Documentation

• Описывай контракты слоев и границы ответственности.
• Фиксируй инварианты агрегатов, версии, side effects и условия ошибок.
• Не превращай документацию в пересказ кода построчно.

5. README and Examples

• README должен покрывать: назначение, запуск, конфигурацию, тесты, структуру и типовые сценарии.
• README не должен быть перегружен: целевое чтение за 2 минуты или меньше.
• Не дублируй в README полную схему конфигурации: опиши способ её передачи и ссылайся на примеры, которыми владеет специализированный скил конфигурации.

6. Update Policy

• Если изменен публичный контракт, обнови docstring сразу в том же PR/изменении.
• Если изменился способ передачи конфигурации, синхронизируй краткую инструкцию и ссылки в README.
• Если поведение изменилось, а документация осталась прежней, это дефект документации.
• Новая документация не должна конфликтовать с тестами и фактическим поведением.

Anti-Patterns

• Пустые или формальные docstring без новой информации.
• Дублирование type hints в тексте.
• Слишком длинные описания без практической пользы.
• Отсутствие обновления docstring после изменения контракта.
• README как огромная простыня, которую нельзя быстро прочитать.
• Дублирование полной схемы конфигурации в README.

Definition of Done

• Документация написана на русском языке.
• Публичные методы и классы имеют краткие, точные docstring.
• Секции Args/Raises/Returns добавлены только там, где это нужно.
• README дает быстрый и достаточный вход за пару минут или меньше.
• README корректно объясняет способ настройки и ведёт к актуальным примерам.
• Документация согласована с фактическим поведением кода.
• Архитектурные границы и контракты отражены без лишней детализации.

References

• Шаблоны docstring: docstring_templates.md
• README: readme_and_examples_guide.md
• Чеклист ревью документации: documentation_review_checklist.md
• Паттерны архитектурного описания: architecture_documentation_patterns.md