docformatter

Dokumentformatierer

Code
Dokumentzeichenfolgen
GitHub
PyPi

Formatiert Dokumentzeichenfolgen so, dass sie PEP 257 folgen.

Merkmale

docformatter formatiert Dokumentzeichenfolgen automatisch so, dass sie einer Teilmenge der PEP 257-Konventionen folgen. Nachfolgend sind die relevanten Punkte aus PEP 257 aufgeführt.

• Aus Konsistenzgründen verwenden Sie Dokumentzeichenfolgen immer in dreifache doppelte Anführungszeichen.
• Dreifache Anführungszeichen werden verwendet, obwohl die Zeichenfolge in eine Zeile passt.
• Mehrzeilige Dokumentzeichenfolgen bestehen wie eine einzeilige Dokumentzeichenfolge aus einer Zusammenfassungszeile, gefolgt von einer Leerzeile und einer ausführlicheren Beschreibung.
• Sofern nicht die gesamte Dokumentzeichenfolge in eine Zeile passt, platzieren Sie die schließenden Anführungszeichen einzeln in einer Zeile.

docformatter verarbeitet auch einige der PEP 8-Konventionen.

• Schreiben Sie keine Zeichenfolgenliterale, die auf erheblichen nachgestellten Leerzeichen basieren. Solche nachgestellten Leerzeichen sind optisch nicht zu unterscheiden und werden von einigen Editoren (oder neuerdings von reindent.py) gekürzt.

docformatter formatiert Dokumentzeichenfolgen, die mit black kompatibel sind, wenn die Option --black übergeben wird.

docformatter formatiert Feldlisten, die Epytext- oder Sphinx-Stile verwenden.

Sehen Sie sich die vollständige Dokumentation unter „read-the-docs“ an, insbesondere den Abschnitt „Anforderungen“ für eine ausführlichere Diskussion von PEP 257 und anderen Anforderungen.

Installation

Von pip:

 $ pip install --upgrade docformatter

Oder wenn Sie pyproject.toml zum Konfigurieren von docformatter verwenden möchten und Python < 3.11 verwenden:

 $ pip install --upgrade docformatter[tomli]

Bei Python >=3.11 wird tomllib aus der Standardbibliothek verwendet.

Oder wenn Sie einen Release Candidate (oder ein anderes Tag) verwenden möchten:

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

Dabei ist das Release Candidate-Tag, das Sie installieren möchten. Release-Kandidaten-Tags haben das Format v1.6.0-rc1. Release-Kandidaten werden auch als Github-Release verfügbar gemacht.

Beispiel

Nach dem Ausführen:

 $ docformatter --in-place example.py

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

wird in dieses formatiert

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

Benutzen Sie Docformatter ? Welchen Docstring-Stil verwenden Sie? Fügen Sie der README-Datei Ihres Projekts einige Abzeichen hinzu und teilen Sie es allen mit.

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

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

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

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

Probleme

Fehler und Patches können auf der GitHub-Seite gemeldet werden.