# Python Repository Documentation

> Используй при документировании Python-репозиториев в прикладных сервисах. Триггеры — описание архитектуры, модулей, публичных методов и контрактов; написание docstring на русском языке в кратком стиле; оформление README и синхронизация документации с изменениями кода. Примеры конфигурации относятся к специализированному скилу конфигурации приложения.

- Skill: `nemagu/python-repository-documentation` (Agent Skill, multi-file: 6 files)
- Install (CLI): `npx skillmds@latest add nemagu/python-repository-documentation`
- Raw SKILL.md: https://api.skillmd.com/api/skills/nemagu/python-repository-documentation/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Docs & Writing
- Author: Nemagu (https://skillmd.com/u/nemagu)
- Updated: 2026-09-21
- Page: https://skillmd.com/skills/nemagu/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](references/docstring_templates.md)
- README: [readme_and_examples_guide.md](references/readme_and_examples_guide.md)
- Чеклист ревью документации: [documentation_review_checklist.md](references/documentation_review_checklist.md)
- Паттерны архитектурного описания: [architecture_documentation_patterns.md](references/architecture_documentation_patterns.md)