Repolode
Enviar
adamchainz

adamchainz/blacken-docs

Ferramenta de linha de comando que executa o Black em blocos de código Python dentro de arquivos de documentação Markdown, reStructuredText e LaTeX.

Ver no GitHub
Estrelas
680
Forks
46
Issues abertas
18
Último commit
há 3 dias

O que é?

blacken-docs reformata exemplos de código Python incorporados à documentação para que sigam o mesmo padrão de formatação do restante do código de um projeto. A ferramenta lida com blocos python e pycon em Markdown e reStructuredText, blocos minted e PythonTeX em LaTeX e conteúdo Markdown ou reST dentro de docstrings Python.

Ela altera diretamente os arquivos informados e retorna um código de saída diferente de zero quando algum arquivo é modificado, o que facilita seu uso em CI ou como hook do pre-commit. Opções do Black, como comprimento máximo da linha, versão-alvo e skip-string-normalization, são repassadas; o modo --check indica as alterações necessárias sem modificar os arquivos.

É possível desativar a formatação de um bloco específico com os comentários blacken-docs:off e blacken-docs:on. Como o Black muda com o tempo, o projeto recomenda fixar a versão do Black na configuração do pre-commit.

Recursos principais

  • 01Formata blocos python e pycon em arquivos Markdown e reStructuredText
  • 02Lida com blocos de código minted e PythonTeX em documentos LaTeX
  • 03Reformata exemplos de código Markdown e reST em docstrings Python
  • 04Oferece o modo --check e retorna um código de saída diferente de zero quando os arquivos são modificados
  • 05Disponibiliza um hook do pre-commit com versões do Black fixadas

Casos de uso

  • Manter a formatação consistente de trechos Python no README ou na documentação Markdown de um projeto
  • Garantir a formatação de exemplos de código em documentação reStructuredText baseada em Sphinx
  • Executar verificações de formatação da documentação em CI ou no pre-commit antes de mesclar alterações

Início rápido

  1. 1

    Instale blacken-docs com pip

    python -m pip install blacken-docs
  2. 2

    Execute blacken-docs nos arquivos de documentação

    blacken-docs README.rst

Antes de usar

  • Formata apenas blocos de código Python em arquivos Markdown, reStructuredText e LaTeX.
  • Não percorre diretórios recursivamente; é necessário informar os nomes dos arquivos ou usar padrões glob ou pre-commit.

Em coleções

Geradores de sites estáticos e ferramentas de documentação

Tópicos

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

Perguntas frequentes

O que é blacken-docs?
Ferramenta de linha de comando que executa o Black em blocos de código Python dentro de arquivos de documentação Markdown, reStructuredText e LaTeX. blacken-docs reformata exemplos de código Python incorporados à documentação para que sigam o mesmo padrão de formatação do restante do código de um projeto. A ferramenta lida com blocos python e pycon em Markdown e reStructuredText, blocos minted e PythonTeX em LaTeX e conteúdo Markdown ou reST dentro de docstrings Python.
blacken-docs é gratuito? Qual é a licença?
blacken-docs é open source sob a licença MIT. Confira os termos da licença antes de usá-lo em produtos comerciais.
blacken-docs ainda é mantido?
Manutenção ativa. O último commit de blacken-docs foi em 4 de nov. de 2026.
Para que posso usar blacken-docs?
Manter a formatação consistente de trechos Python no README ou na documentação Markdown de um projeto Garantir a formatação de exemplos de código em documentação reStructuredText baseada em Sphinx Executar verificações de formatação da documentação em CI ou no pre-commit antes de mesclar alterações
Como instalar blacken-docs?
Instale blacken-docs com pip: python -m pip install blacken-docs Execute blacken-docs nos arquivos de documentação: blacken-docs README.rst
Onde consigo blacken-docs?
O código-fonte e as instruções de instalação estão no GitHub: https://github.com/adamchainz/blacken-docs

Resumo gerado por IA a partir do README do projeto. As estatísticas do GitHub são atualizadas diariamente.

Projetos relacionados