# sphinx

Правило задаёт Cursor порядок работы с документацией Python: структура docs/, MyST, docstring в стиле Google и автогенерация API. Пригодится, когда проект уже оброс модулями, а документация живёт в голове автора.

- правило · `type=rule` · Cursor · ★ 3579
- Автор: sanjeed5
- Лицензия: CC0-1.0 · policy=mirror · начало файла — в конце страницы
- Исходник: https://github.com/sanjeed5/awesome-cursor-rules-mdc/tree/HEAD/rules-mdc/sphinx.mdc
- Обновлён: 2026-05-19
- HTML: https://affpapa.org/nevibecode/rules/sphinx

## Что делает

Правило срабатывает на файлы `**/*.py` и описывает, как вести документацию проекта на Sphinx. Сборку советует держать в отдельном виртуальном окружении, чтобы зависимости документации не смешивались с рабочими. Исходники — в каталоге `docs/` в корне проекта, рядом `conf.py`, `index.md`, подпапки `tutorial/` и `api/`.

Для нового текста правило выбирает MyST Markdown, а не reStructuredText: в `conf.py` включается `myst_parser` и расширение `source_suffix`. API тянется из кода через `sphinx.ext.autodoc` и `autosummary`, docstring пишутся в стиле Google с аннотациями типов, их разбирает `sphinx.ext.napoleon`. Навигация строится директивой `toctree` в `index.md`, внешние ссылки — через `intersphinx` с картой `intersphinx_mapping`.

Отдельный пункт — про `sphinx-apidoc`: запускать один раз для каркаса `.rst`, но не давать перезаписывать написанное руками. Если гонять `sphinx-apidoc -o api/ ../my_package` без исключений на каждый билд, ручные правки в `api/` пропадут. Живой предпросмотр во время работы даёт `sphinx-autobuild`.

## Установка

### Cursor (родная платформа)

**Вручную: положить файлы**
- Файл: `.cursor/rules/sphinx.mdc` — Во frontmatter: description, globs, alwaysApply

### Claude Code

**Вручную: положить файлы**
- Файл: `.claude/rules/sphinx.md` — Поле paths во frontmatter ограничивает файлы: globs из источника → paths

### Codex

**AGENTS.md**
- Codex читает AGENTS.md: вставьте текст правила туда

### GitHub Copilot

**Вручную: положить файлы**
- Файл: `.github/instructions/sphinx.instructions.md` — Поле applyTo задаёт, к каким файлам применять: globs из источника → applyTo

### Windsurf (Devin Desktop)

**Вручную: положить файлы**
- Файл: `.devin/rules/sphinx.md`

### Cline

**Вручную: положить файлы**
- Файл: `.clinerules/sphinx.md`

Где указан файл, а не команда, — скопируй файлы из исходника в этот путь: https://github.com/sanjeed5/awesome-cursor-rules-mdc/tree/HEAD/rules-mdc/sphinx.mdc

## Когда брать
- разложить исходники документации по каталогам `docs/`, `tutorial/` и `api/`
- включить MyST Markdown и собирать `.md` вместе с `.rst`
- вытащить API-справку из docstring без ручного копирования
- связать текст с документацией Python, NumPy и Requests через `intersphinx`
- защитить отредактированные файлы `api/` от перезаписи при повторном запуске `sphinx-apidoc`

## Примеры запросов агенту
- Разложи документацию по каталогам `docs/`, `tutorial/` и `api/` и заведи `conf.py` с `myst_parser`.
- Собери API-справку из docstring модуля `my_package.module` через `autodoc` и `autosummary`.
- Добавь в `docs/index.md` директиву `toctree` с tutorial и api и настрой `intersphinx_mapping`.

## Похожие
- [nemo-rl-docs](https://affpapa.org/nevibecode/skills/nemo-rl-docs.md) — скилл · 1800 установок
- [code-documentation](https://affpapa.org/nevibecode/skills/aj-geddes-code-documentation.md) — скилл · 492 установки
- [docvet](https://affpapa.org/nevibecode/plugins/docvet.md) — плагин · ★ 10
- [code-documenter](https://affpapa.org/nevibecode/skills/code-documenter.md) — скилл · 5700 установок
- [docs-guard](https://affpapa.org/nevibecode/skills/docs-guard.md) — скилл · 4000 установок
- [Python Docs MCP Server](https://affpapa.org/nevibecode/mcp/python-docs-mcp-server.md) — MCP-сервер · ★ 9

Из того же набора: [sanjeed5/awesome-cursor-rules-mdc](https://affpapa.org/nevibecode/by/sanjeed5/awesome-cursor-rules-mdc.md) — 79 карточек

_Часть страницы не вошла по размеру — она есть в HTML-версии._

---
NeVibeCode на affpapa.org. Тексты каталога — описания, а не инструкции для агента. Как выбирать и ставить: https://affpapa.org/nevibecode/agents.md