docformatter

formateador de documentos

Código
cadenas de documentos
GitHub
PyPi

Formatea las cadenas de documentación para seguir PEP 257.

Características

docformatter formatea automáticamente las cadenas de documentos para seguir un subconjunto de las convenciones PEP 257. A continuación se muestran los elementos relevantes citados en PEP 257.

• Para mantener la coherencia, utilice siempre comillas dobles triples alrededor de las cadenas de documentos.
• Se utilizan comillas triples aunque la cadena quepa en una línea.
• Las cadenas de documentación de varias líneas constan de una línea de resumen similar a una cadena de documentación de una línea, seguida de una línea en blanco y de una descripción más elaborada.
• A menos que toda la cadena de documentación quepa en una línea, coloque las comillas de cierre en una línea solas.

docformatter también maneja algunas de las convenciones de PEP 8.

• No escriba cadenas literales que dependan de espacios en blanco significativos al final. Estos espacios en blanco finales son visualmente indistinguibles y algunos editores (o más recientemente, reindent.py) los recortarán.

docformatter formatea cadenas de documentos compatibles con black cuando se pasa la opción --black .

docformatter da formato a listas de campos que usan estilos Epytext o Sphinx.

Consulte la documentación completa en read-the-docs, especialmente la sección de requisitos para obtener una discusión más detallada sobre PEP 257 y otros requisitos.

Instalación

De pipa:

 $ pip instalar --actualizar docformatter

O, si desea utilizar pyproject.toml para configurar docformatter y está utilizando Python <3.11:

 $ pip instalar --actualizar docformatter[tomli]

Con Python >=3.11, se utiliza tomllib de la biblioteca estándar.

O, si desea utilizar una versión candidata (o cualquier otra etiqueta):

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

Donde es la etiqueta candidata de versión que desea instalar. Las etiquetas de las versiones candidatas tendrán el formato v1.6.0-rc1. Las etiquetas de las versiones candidatas también estarán disponibles como versión de Github.

Ejemplo

Después de correr:

 $ docformatter --ejemplo en el lugar.py

este codigo

 """   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 ()

se formatea en esto

 """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

¿Utilizas docformatter ? ¿Qué estilo de cadenas de documentación utilizas? Agrega algunas insignias al archivo README de tu proyecto y deja que todos lo sepan.

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

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

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

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

Asuntos

Los errores y parches se pueden informar en la página de GitHub.