docformatter

formateur de documents

Code
Docstrings
GitHub
PyPi

Formate les docstrings pour suivre le PEP 257.

Caractéristiques

docformatter formate automatiquement les docstrings pour suivre un sous-ensemble des conventions PEP 257. Vous trouverez ci-dessous les éléments pertinents cités du PEP 257.

• Pour des raisons de cohérence, utilisez toujours des guillemets triples autour des docstrings.
• Les guillemets triples sont utilisés même si la chaîne tient sur une seule ligne.
• Les docstrings multilignes se composent d'une ligne récapitulative, tout comme une docstring d'une seule ligne, suivie d'une ligne vide, suivie d'une description plus élaborée.
• À moins que la totalité de la docstring ne tienne sur une ligne, placez les guillemets fermants seuls sur une ligne.

docformatter gère également certaines des conventions PEP 8.

• N'écrivez pas de chaînes littérales qui reposent sur des espaces de fin importants. De tels espaces de fin sont visuellement impossibles à distinguer et certains éditeurs (ou plus récemment, reindent.py) les supprimeront.

docformatter formate les docstrings compatibles avec black lorsque l'option --black est passée.

docformatter formate des listes de champs qui utilisent les styles Epytext ou Sphinx.

Consultez la documentation complète sur read-the-docs, en particulier la section sur les exigences pour une discussion plus détaillée du PEP 257 et d'autres exigences.

Installation

De pip :

 $ pip install --upgrade docformatter

Ou, si vous souhaitez utiliser pyproject.toml pour configurer docformatter et que vous utilisez Python < 3.11 :

 $ pip install --upgrade docformatter[tomli]

Avec Python >=3.11, tomllib de la bibliothèque standard est utilisé.

Ou, si vous souhaitez utiliser une version candidate (ou toute autre balise) :

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

Où est la balise release candidate que vous souhaitez installer. Les balises de version candidate auront le format v1.6.0-rc1. Les versions candidates seront également disponibles en tant que version Github.

Exemple

Après avoir exécuté :

 $ docformatter --in-place exemple.py

ce code

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

est formaté dans ceci

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

Commercialisation

Utilisez-vous docformatter ? Quel style de docstrings utilisez-vous ? Ajoutez quelques badges au README de votre projet et faites-le savoir à tout le monde.

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

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

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

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

Problèmes

Les bugs et correctifs peuvent être signalés sur la page GitHub.