docformatter

formato de documento

Código
Documentos
GitHub
PyPi

Formata docstrings para seguir o PEP 257.

Características

docformatter formata automaticamente docstrings para seguir um subconjunto das convenções PEP 257. Abaixo estão os itens relevantes citados no PEP 257.

• Para consistência, sempre use aspas duplas triplas em torno de docstrings.
• Aspas triplas são usadas mesmo que a string caiba em uma linha.
• Docstrings multilinhas consistem em uma linha de resumo como uma docstring de uma linha, seguida por uma linha em branco, seguida por uma descrição mais elaborada.
• A menos que toda a documentação caiba em uma linha, coloque as aspas de fechamento sozinhas em uma linha.

docformatter também lida com algumas das convenções PEP 8.

• Não escreva literais de string que dependam de espaços em branco significativos. Esses espaços em branco finais são visualmente indistinguíveis e alguns editores (ou mais recentemente, reindent.py) irão cortá-los.

docformatter formata docstrings compatíveis com black quando passada a opção --black .

docformatter formata listas de campos que usam estilos Epytext ou Sphinx.

Veja a documentação completa em read-the-docs, especialmente a seção de requisitos para uma discussão mais detalhada do PEP 257 e outros requisitos.

Instalação

Do pip:

 $ pip install --upgrade docformatter

Ou, se você quiser usar pyproject.toml para configurar o docformatter e estiver usando Python <3.11:

 $ pip install --upgrade docformatter[tomli]

Com Python >=3.11, é usado tomllib da biblioteca padrão.

Ou, se você quiser usar um release candidate (ou qualquer outra tag):

 $ pip instalar git+https://github.com/PyCQA/docformatter.git@

Onde é a tag release candidate que você deseja instalar. As tags de candidato a lançamento terão o formato v1.6.0-rc1 Os candidatos a lançamento também serão disponibilizados como uma versão do Github.

Exemplo

Depois de correr:

 $ docformatter --in-place exemplo.py

este código

 """   Here are some examples.

    This module docstring should be dedented."""


def launch_rocket ():
    """Launch
the
rocket. Go colonize space."""


def factorial ( x ):
    '''

    Return x factorial.

    This uses math.factorial.

    '''
    import math
    return math . factorial ( x )


def print_factorial ( x ):
    """Print x factorial"""
    print ( factorial ( x ))


def main ():
    """Main
    function"""
    print_factorial ( 5 )
    if factorial ( 10 ):
        launch_rocket ()

é formatado neste

 """Here are some examples.

This module docstring should be dedented.
"""


def launch_rocket ():
    """Launch the rocket.

    Go colonize space.
    """


def factorial ( x ):
    """Return x factorial.

    This uses math.factorial.
    """
    import math
    return math . factorial ( x )


def print_factorial ( x ):
    """Print x factorial."""
    print ( factorial ( x ))


def main ():
    """Main function."""
    print_factorial ( 5 )
    if factorial ( 10 ):
        launch_rocket ()

Marketing

Você usa docformatter ? Que doutrinas de estilo você usa? Adicione alguns emblemas ao README do seu projeto e informe a todos.

 .. imagem:: https://img.shields.io/badge/%20formatter-docformatter-fedcba.svg
    :target: https://github.com/PyCQA/docformatter

.. imagem:: https://img.shields.io/badge/%20style-sphinx-0a507a.svg
    :target: https://www.sphinx-doc.org/en/master/usage/index.html

.. imagem:: https://img.shields.io/badge/%20style-numpy-459db9.svg
    :target: https://numpydoc.readthedocs.io/en/latest/format.html

.. imagem:: https://img.shields.io/badge/%20style-google-3666d6.svg
    :target: https://google.github.io/styleguide/pyguide.html#s3.8-comments-and-docstrings

Problemas

Bugs e patches podem ser relatados na página do GitHub.