Generador de documentación para Python que crea HTML, PDF, EPUB y otros formatos a partir de fuentes reStructuredText o Markdown.
8,1 mil2,6 milPythonOtherActualizado hace 6 días
adamchainz/blacken-docs
Herramienta de línea de comandos que ejecuta Black en bloques de código Python dentro de archivos de documentación Markdown, reStructuredText y LaTeX.
- Estrellas
- 680
- Forks
- 46
- Issues abiertos
- 18
- Último commit
- hace 3 días
¿Qué es?
blacken-docs reformatea los ejemplos de código Python incluidos en la documentación para que sigan el mismo estilo que el resto del código de un proyecto. Admite bloques python y pycon en Markdown y reStructuredText, bloques minted y PythonTeX en LaTeX, y contenido Markdown o reST dentro de docstrings de Python.
Modifica directamente los archivos que le pases y devuelve un código de salida distinto de cero si cambia alguno, por lo que es fácil usarlo en CI o como hook de pre-commit. Permite pasar opciones de Black como la longitud de línea, la versión de destino y skip-string-normalization, y el modo --check informa de los cambios necesarios sin modificar los archivos.
Los comentarios blacken-docs:off y blacken-docs:on permiten desactivar el formateo para un bloque específico. Como Black cambia con el tiempo, el proyecto recomienda fijar su versión en la configuración de pre-commit.
Funciones clave
- 01Formatea bloques python y pycon en archivos Markdown y reStructuredText
- 02Admite bloques de código minted y PythonTeX en documentos LaTeX
- 03Reformatea ejemplos de código Markdown y reST dentro de docstrings de Python
- 04Ofrece el modo --check y devuelve un código de salida distinto de cero si cambia algún archivo
- 05Se distribuye como hook de pre-commit con versiones de Black fijadas
Casos de uso
- Mantener un formato coherente en los fragmentos de Python del README o la documentación Markdown de un proyecto
- Aplicar un formato uniforme a los ejemplos de código en la documentación reStructuredText basada en Sphinx
- Ejecutar comprobaciones de formato de la documentación en CI o con pre-commit antes de fusionar cambios
Inicio rápido
- 1
Instala blacken-docs con pip
python -m pip install blacken-docs - 2
Ejecuta blacken-docs en tus archivos de documentación
blacken-docs README.rst
Antes de usarlo
- Solo formatea bloques de código Python dentro de archivos Markdown, reStructuredText y LaTeX.
- No recorre los directorios de forma recursiva; debes pasarle los nombres de los archivos o usar patrones glob o pre-commit.
En colecciones
Temas
Preguntas frecuentes
- ¿Qué es blacken-docs?
- Herramienta de línea de comandos que ejecuta Black en bloques de código Python dentro de archivos de documentación Markdown, reStructuredText y LaTeX. blacken-docs reformatea los ejemplos de código Python incluidos en la documentación para que sigan el mismo estilo que el resto del código de un proyecto. Admite bloques python y pycon en Markdown y reStructuredText, bloques minted y PythonTeX en LaTeX, y contenido Markdown o reST dentro de docstrings de Python.
- ¿blacken-docs es gratuito? ¿Qué licencia tiene?
- blacken-docs es open source bajo la licencia MIT. Revisa los términos de la licencia antes de usarlo en productos comerciales.
- ¿blacken-docs sigue mantenido?
- Mantenimiento activo. El último commit de blacken-docs fue el 4 nov 2026.
- ¿Para qué puedo usar blacken-docs?
- Mantener un formato coherente en los fragmentos de Python del README o la documentación Markdown de un proyecto Aplicar un formato uniforme a los ejemplos de código en la documentación reStructuredText basada en Sphinx Ejecutar comprobaciones de formato de la documentación en CI o con pre-commit antes de fusionar cambios
- ¿Cómo se instala blacken-docs?
- Instala blacken-docs con pip: python -m pip install blacken-docs Ejecuta blacken-docs en tus archivos de documentación: blacken-docs README.rst
- ¿Dónde consigo blacken-docs?
- El código fuente y las instrucciones de instalación están en GitHub: https://github.com/adamchainz/blacken-docs
Resumen generado por IA a partir del README del proyecto. Las estadísticas de GitHub se actualizan a diario.
Proyectos relacionados
Una herramienta CLI para ejecutar linters y formateadores de Python, como ruff, isort, black, mypy y flake8, directamente en Jupyter Notebooks.
1,2 mil52PythonMITActualizado hace 21 horas
Generador de sitios de documentación que convierte archivos Markdown en un sitio web sin necesidad de un paso de compilación.
31,6 mil+6 esta semana5,8 milJavaScriptMITBien mantenidoActualizado anteayer
Framework de documentación en TypeScript que crea sitios a partir de Markdown/MDX y genera documentación de API para OpenAPI y GraphQL.
1159TypeScriptMITActualizado hace 9 días
Herramienta de Python y hook de pre-commit que añade automáticamente comas finales a llamadas, literales y definiciones multilínea.
37328PythonMITBien mantenidoActualizado hace 3 días
CMS flat-file que crea sitios web informativos y eBooks a partir de archivos Markdown, sin necesidad de una base de datos.
620+2 esta semana75JavaScriptMITBien mantenidoActualizado anteayer