Repolode
Предложить
adamchainz

adamchainz/blacken-docs

CLI-инструмент, который запускает Black для блоков кода на Python в документации Markdown, reStructuredText и LaTeX.

Открыть на GitHub
Звёзды
680
Форки
46
Открытые issues
18
Последний коммит
вчера

Что это?

blacken-docs перезаписывает примеры кода на Python, встроенные в документацию, чтобы они форматировались так же, как остальной код проекта. Инструмент обрабатывает блоки python и pycon в Markdown и reStructuredText, блоки minted и PythonTeX в LaTeX, а также Markdown или reST внутри docstring на Python.

Инструмент изменяет переданные файлы на месте и возвращает ненулевой код завершения, если файл был изменён — поэтому его удобно использовать в CI или как pre-commit hook. Параметры Black, например длина строки, целевая версия и skip-string-normalization, передаются дальше, а режим --check сообщает о необходимых изменениях, не изменяя файлы.

Форматирование отдельного блока можно отключить комментариями blacken-docs:off и blacken-docs:on. Поскольку Black со временем меняется, проект рекомендует закреплять его версию в конфигурации pre-commit.

Ключевые возможности

  • 01Форматирует блоки python и pycon в файлах Markdown и reStructuredText
  • 02Обрабатывает блоки кода minted и PythonTeX в документах LaTeX
  • 03Повторно форматирует примеры кода Markdown и reST внутри docstring на Python
  • 04Поддерживает режим --check и возвращает ненулевой код завершения, если файлы изменились
  • 05Поставляется как pre-commit hook с закреплёнными версиями Black

Сценарии использования

  • Поддержание единообразного форматирования фрагментов кода на Python в README проекта или документации Markdown
  • Проверка форматирования примеров кода в документации reStructuredText на базе Sphinx
  • Запуск проверок форматирования документации в CI или через pre-commit перед слиянием изменений

Быстрый старт

  1. 1

    Установите blacken-docs с помощью pip

    python -m pip install blacken-docs
  2. 2

    Запустите blacken-docs для файлов документации

    blacken-docs README.rst

Что важно знать

  • Форматирует только блоки кода Python в файлах Markdown, reStructuredText и LaTeX.
  • Не обходит каталоги рекурсивно; необходимо указать имена файлов или использовать шаблоны glob либо pre-commit.

В подборках

Генераторы статических сайтов и инструменты для документации

Темы

#python#black#documentation#code-formatting#pre-commit#markdown#restructuredtext#latex#docs

Частые вопросы

Что такое blacken-docs?
CLI-инструмент, который запускает Black для блоков кода на Python в документации Markdown, reStructuredText и LaTeX. blacken-docs перезаписывает примеры кода на Python, встроенные в документацию, чтобы они форматировались так же, как остальной код проекта. Инструмент обрабатывает блоки python и pycon в Markdown и reStructuredText, блоки minted и PythonTeX в LaTeX, а также Markdown или reST внутри docstring на Python.
blacken-docs можно использовать бесплатно? Какая у него лицензия?
blacken-docs распространяется с открытым исходным кодом под лицензией MIT. Перед использованием в коммерческих продуктах проверьте условия лицензии.
blacken-docs всё ещё поддерживается?
Активно поддерживается. Последний коммит в blacken-docs — 4 нояб. 2026 г..
Для чего можно использовать blacken-docs?
Поддержание единообразного форматирования фрагментов кода на Python в README проекта или документации Markdown Проверка форматирования примеров кода в документации reStructuredText на базе Sphinx Запуск проверок форматирования документации в CI или через pre-commit перед слиянием изменений
Как установить blacken-docs?
Установите blacken-docs с помощью pip: python -m pip install blacken-docs Запустите blacken-docs для файлов документации: blacken-docs README.rst
Где скачать blacken-docs?
Исходный код и инструкции по установке — на GitHub: https://github.com/adamchainz/blacken-docs

Описание создано ИИ на основе README проекта. Статистика GitHub обновляется ежедневно.

Похожие проекты