TOC

Dokumentation von Python-Code: Eine vollständige Anleitung

Dokumentation von Python-Code: Eine vollständige Anleitung

Willkommen zu Ihrer vollständigen Anleitung zur Dokumentation von Python-Code. Egal, ob Sie ein kleines Skript oder ein großes Projekt dokumentieren, ob Sie ein Anfänger oder ein erfahrener Pythonista sind, in diesem Handbuch finden Sie alles, was Sie wissen müssen.

Wir haben dieses Tutorial in vier Hauptabschnitte unterteilt:

  1. Why Documenting Your Code Is So Important: Eine Einführung in die Dokumentation und ihre Bedeutung

  2. Commenting vs. Documenting Code: Ein Überblick über die Hauptunterschiede zwischen Kommentieren und Dokumentieren sowie über die geeigneten Zeiten und Möglichkeiten zur Verwendung von Kommentaren

  3. Documenting Your Python Code Base Using Docstrings: Ein tiefer Einblick in die Dokumentzeichenfolgen für Klassen, Klassenmethoden, Funktionen, Module, Pakete und Skripte sowie in die darin enthaltenen Informationen

  4. Documenting Your Python Projects: Die erforderlichen Elemente und was sie für Ihre Python-Projekte enthalten sollten

Lesen Sie dieses Tutorial von Anfang bis Ende durch oder springen Sie zu einem Abschnitt, an dem Sie interessiert sind. Es wurde entwickelt, um in beide Richtungen zu funktionieren.

Warum die Dokumentation Ihres Codes so wichtig ist

Wenn Sie dieses Tutorial lesen, wissen Sie hoffentlich bereits, wie wichtig es ist, Ihren Code zu dokumentieren. Aber wenn nicht, dann zitiere ich etwas, das Guido mir kürzlich auf einer PyCon gesagt hat:

"Code wird häufiger gelesen als geschrieben."

-Guido van Rossum

Wenn Sie Code schreiben, schreiben Sie ihn für zwei Hauptgruppen: Ihre Benutzer und Ihre Entwickler (einschließlich Sie selbst). Beide Zielgruppen sind gleich wichtig. Wenn Sie wie ich sind, haben Sie wahrscheinlich alte Codebasen geöffnet und sich gefragt: "Was in aller Welt habe ich gedacht?" Wenn Sie Probleme beim Lesen Ihres eigenen Codes haben, stellen Sie sich vor, was Ihre Benutzer oder andere Entwickler erleben, wenn sie versuchen, Ihren Code zu verwenden oder dazu beizutragen.

Umgekehrt bin ich mir sicher, dass Sie in eine Situation geraten sind, in der Sie etwas in Python tun wollten und eine großartige Bibliothek gefunden haben, mit der Sie Ihre Arbeit erledigen können. Wenn Sie jedoch mit der Verwendung der Bibliothek beginnen, suchen Sie nach Beispielen, Aufzeichnungen oder sogar offiziellen Dokumentationen, wie Sie etwas Bestimmtes tun können, und können die Lösung nicht sofort finden.

Nach der Suche stellen Sie fest, dass die Dokumentation fehlt oder noch schlimmer ist und vollständig fehlt. Dies ist ein frustrierendes Gefühl, das Sie davon abhält, die Bibliothek zu verwenden, egal wie groß oder effizient der Code ist. Daniele Procida fasste diese Situation am besten zusammen:

"Es spielt keine Rolle, wie gut Ihre Software ist, dennif the documentation is not good enough, people will not use it."

-Daniele Procida

In diesem Handbuch erfahren Sie von Grund auf, wie Sie Ihren Python-Code vom kleinsten Skript bis zum größten Python-Projekt ordnungsgemäß dokumentieren, um zu verhindern, dass Ihre Benutzer sich jemals zu frustriert fühlen, um Ihr Projekt zu verwenden oder dazu beizutragen.

Kommentar vs. Code dokumentieren

Bevor wir uns mit der Dokumentation Ihres Python-Codes befassen können, müssen wir die Dokumentation von der Kommentierung unterscheiden.

Im Allgemeinen beschreibt das Kommentieren Ihren Code für / für Entwickler. Das beabsichtigte Hauptpublikum sind die Betreuer und Entwickler des Python-Codes. In Verbindung mit gut geschriebenem Code helfen Kommentare dem Leser, Ihren Code sowie dessen Zweck und Design besser zu verstehen:

„Code sagt dir wie; Kommentare sagen dir warum. "

-Jeff Atwood (aka Coding Horror)

Das Dokumentieren von Code beschreibt seinen Benutzern seine Verwendung und Funktionalität. Während es im Entwicklungsprozess hilfreich sein kann, sind die Benutzer die Hauptzielgruppe. Im folgenden Abschnitt wird beschrieben, wie und wann Sie Ihren Code kommentieren müssen.

Grundlagen des Kommentierens von Code

Kommentare werden in Python mit dem Nummernzeichen (#) erstellt und sollten kurze Aussagen sein, die nicht länger als ein paar Sätze sind. Hier ist ein einfaches Beispiel: 

def hello_world():
    # A simple comment preceding a simple print statement
    print("Hello World")

LautPEP 8 sollten Kommentare eine maximale Länge von 72 Zeichen haben. Dies gilt auch dann, wenn Ihr Projekt die maximale Zeilenlänge so ändert, dass sie größer als die empfohlenen 80 Zeichen ist. Wenn ein Kommentar größer als das Limit für Kommentarzeichen sein soll, ist die Verwendung mehrerer Zeilen für den Kommentar angemessen: 

def hello_long_world():
    # A very long statement that just goes on and on and on and on and
    # never ends until after it's reached the 80 char limit
    print("Hellooooooooooooooooooooooooooooooooooooooooooooooooooooooo World")

Das Kommentieren Ihres Codes dientmultiple purposes, including:

  • Planning and Reviewing: Wenn Sie neue Teile Ihres Codes entwickeln, kann es angebracht sein, zuerst Kommentare zu verwenden, um diesen Codeabschnitt zu planen oder zu skizzieren. Denken Sie daran, diese Kommentare zu entfernen, sobald die eigentliche Codierung implementiert und überprüft / getestet wurde: 

    # First step
# Second step
# Third step

  • Code Description: Kommentare können verwendet werden, um die Absicht bestimmter Codeabschnitte zu erläutern: 

    # Attempt a connection based on previous settings. If unsuccessful,
# prompt user for new settings.

  • Algorithmic Description: Wenn Algorithmen verwendet werden, insbesondere komplizierte, kann es hilfreich sein, zu erklären, wie der Algorithmus funktioniert oder wie er in Ihrem Code implementiert ist. Es kann auch angebracht sein, zu beschreiben, warum ein bestimmter Algorithmus einem anderen vorgezogen wurde. 

    # Using quick sort for performance gains

  • Tagging: Die Verwendung von Tagging kann verwendet werden, um bestimmte Codeabschnitte zu kennzeichnen, in denen bekannte Probleme oder Verbesserungsbereiche liegen. Einige Beispiele sind:BUG,FIXME undTODO. 

    # TODO: Add condition for when val is None

Kommentare zu Ihrem Code sollten kurz und konzentriert gehalten werden. Vermeiden Sie nach Möglichkeit lange Kommentare. Zusätzlich sollten Sie die folgenden vier wesentlichen Regeln alssuggested by Jeff Atwood verwenden:

  1. Halten Sie Kommentare so nah wie möglich am beschriebenen Code. Kommentare, die sich nicht in der Nähe des Beschreibungscodes befinden, sind für den Leser frustrierend und werden bei Aktualisierungen leicht übersehen.

  2. Verwenden Sie keine komplexen Formatierungen (z. B. Tabellen oder ASCII-Abbildungen). Komplexe Formatierungen führen zu störenden Inhalten und können im Laufe der Zeit schwierig zu pflegen sein.

  3. Fügen Sie keine redundanten Informationen hinzu. Angenommen, der Leser des Codes verfügt über ein grundlegendes Verständnis der Programmierprinzipien und der Sprachsyntax.

  4. Entwerfen Sie Ihren Code, um sich selbst zu kommentieren. Der einfachste Weg, Code zu verstehen, ist das Lesen. Wenn Sie Ihren Code mit klaren, leicht verständlichen Konzepten entwerfen, kann der Leser Ihre Absicht schnell konzipieren.

Denken Sie daran, dass Kommentare für den Leser, einschließlich Sie selbst, erstellt wurden, um ihn beim Verständnis des Zwecks und des Designs der Software zu unterstützen.

Kommentieren von Code über Typhinweise (Python 3.5+)

Tipphinweise wurden zu Python 3.5 hinzugefügt und sind ein zusätzliches Formular, das den Lesern Ihres Codes hilft. Tatsächlich bringt es Jeffs vierten Vorschlag von oben auf die nächste Ebene. Es ermöglicht dem Entwickler, Teile seines Codes ohne Kommentare zu entwerfen und zu erklären. Hier ein kurzes Beispiel: 

def hello_name(name: str) -> str:
    return(f"Hello {name}")

Anhand der Typhinweise können Sie sofort erkennen, dass die Funktion erwartet, dass die Eingabename vom Typstr oder einer Zeichenfolge ist. Sie können auch feststellen, dass die erwartete Ausgabe der Funktion vom Typstr oder auch vom Typ ist. Während Typhinweise zur Reduzierung von Kommentaren beitragen, sollten Sie berücksichtigen, dass dies auch zusätzliche Arbeit beim Erstellen oder Aktualisieren Ihrer Projektdokumentation bedeuten kann.

Weitere Informationen zu Typhinweisen und Typprüfungen finden Sie unterthis video created by Dan Bader.

Dokumentieren Ihrer Python-Codebasis mithilfe von Docstrings

Nachdem wir nun das Kommentieren gelernt haben, wollen wir uns eingehend mit der Dokumentation einer Python-Codebasis befassen. In diesem Abschnitt erfahren Sie mehr über Dokumentzeichenfolgen und deren Verwendung für die Dokumentation. Dieser Abschnitt ist weiter in die folgenden Unterabschnitte unterteilt:

  1. Docstrings Background: Hintergrundinformationen zur internen Funktionsweise von Docstrings in Python

  2. Docstring Types: Die verschiedenen Dokumentstringtypen (Funktion, Klasse, Klassenmethode, Modul, Paket und Skript)

  3. Docstring Formats: Die verschiedenen Dokumentzeichenfolgenformate (Google, NumPy / SciPy, reStructured Text und Epytext)

Docstrings Hintergrund

Die Dokumentation Ihres Python-Codes konzentriert sich ausschließlich auf Dokumentzeichenfolgen. Hierbei handelt es sich um integrierte Zeichenfolgen, die bei korrekter Konfiguration Ihren Benutzern und sich selbst bei der Dokumentation Ihres Projekts helfen können. Neben Docstrings verfügt Python auch über die integrierte Funktionhelp(), mit der die Docstring-Objekte an die Konsole gedruckt werden. Hier ein kurzes Beispiel:

>>> 

>>> help(str)
Help on class str in module builtins:

class str(object)
 |  str(object='') -> str
 |  str(bytes_or_buffer[, encoding[, errors]]) -> str
 |
 |  Create a new string object from the given object. If encoding or
 |  errors are specified, then the object must expose a data buffer
 |  that will be decoded using the given encoding and error handler.
 |  Otherwise, returns the result of object.__str__() (if defined)
 |  or repr(object).
 |  encoding defaults to sys.getdefaultencoding().
 |  errors defaults to 'strict'.
 # Truncated for readability

Wie wird diese Ausgabe generiert? Da alles in Python ein Objekt ist, können Sie das Verzeichnis des Objekts mit dem Befehldir() untersuchen. Lassen Sie uns das tun und sehen, was Sie finden:

>>> 

>>> dir(str)
['__add__', ..., '__doc__', ..., 'zfill'] # Truncated for readability

Innerhalb dieser Verzeichnisausgabe gibt es eine interessante Eigenschaft,__doc__. Wenn Sie diese Eigenschaft untersuchen, werden Sie Folgendes feststellen:

>>> 

>>> print(str.__doc__)
str(object='') -> str
str(bytes_or_buffer[, encoding[, errors]]) -> str

Create a new string object from the given object. If encoding or
errors are specified, then the object must expose a data buffer
that will be decoded using the given encoding and error handler.
Otherwise, returns the result of object.__str__() (if defined)
or repr(object).
encoding defaults to sys.getdefaultencoding().
errors defaults to 'strict'.

Voilà! Sie haben gefunden, wo Dokumentzeichenfolgen im Objekt gespeichert sind. Dies bedeutet, dass Sie diese Eigenschaft direkt bearbeiten können. Es gibt jedoch Einschränkungen für eingebaute Geräte:

>>> 

>>> str.__doc__ = "I'm a little string doc! Short and stout; here is my input and print me for my out"
Traceback (most recent call last):
  File "", line 1, in 
TypeError: can't set attributes of built-in/extension type 'str'

Jedes andere benutzerdefinierte Objekt kann bearbeitet werden: 

def say_hello(name):
    print(f"Hello {name}, is it me you're looking for?")

say_hello.__doc__ = "A simple function that says hello... Richie style"

>>> 

>>> help(say_hello)
Help on function say_hello in module __main__:

say_hello(name)
    A simple function that says hello... Richie style

Python verfügt über eine weitere Funktion, die die Erstellung von Dokumentzeichenfolgen vereinfacht. Anstatt die Eigenschaft__doc__direkt zu bearbeiten, wird durch die strategische Platzierung des Zeichenfolgenliteral direkt unter dem Objekt automatisch der Wert__doc__festgelegt. Folgendes passiert mit demselben Beispiel wie oben: 

def say_hello(name):
    """A simple function that says hello... Richie style"""
    print(f"Hello {name}, is it me you're looking for?")

>>> 

>>> help(say_hello)
Help on function say_hello in module __main__:

say_hello(name)
    A simple function that says hello... Richie style

Los geht's! Jetzt verstehen Sie den Hintergrund von Docstrings. Jetzt ist es an der Zeit, sich über die verschiedenen Arten von Dokumentzeichenfolgen und deren Informationen zu informieren.

Docstring-Typen

Docstring-Konventionen werden inPEP 257 beschrieben. Sie sollen Ihren Benutzern einen kurzen Überblick über das Objekt geben. Sie sollten so kurz gehalten werden, dass sie leicht zu warten sind, aber dennoch so ausführlich, dass neue Benutzer ihren Zweck und die Verwendung des dokumentierten Objekts verstehen.

In allen Fällen sollten die Dokumentzeichenfolgen das Zeichenfolgenformat mit dreifach doppeltem Anführungszeichen (""") verwenden. Dies sollte unabhängig davon erfolgen, ob die Dokumentzeichenfolge mehrzeilig ist oder nicht. Ein Dokumentstring sollte mindestens eine kurze Zusammenfassung dessen sein, was Sie beschreiben, und sollte in einer einzigen Zeile enthalten sein: 

"""This is a quick summary line used as a description of the object."""

Mehrzeilige Dokumentzeichenfolgen werden verwendet, um das Objekt über die Zusammenfassung hinaus näher zu erläutern. Alle mehrzeiligen Dokumentzeichenfolgen bestehen aus folgenden Teilen:

  • Eine einzeilige Zusammenfassungszeile

  • Eine leere Zeile in der Zusammenfassung

  • Jede weitere Ausarbeitung für den Docstring

  • Noch eine leere Zeile 

"""This is the summary line

This is the further elaboration of the docstring. Within this section,
you can elaborate further on details as appropriate for the situation.
Notice that the summary and the elaboration is separated by a blank new
line.
"""

# Notice the blank line above. Code should continue on this line.

Alle Dokumentzeichenfolgen sollten dieselbe maximale Zeichenlänge wie Kommentare haben (72 Zeichen). Docstrings können weiter in drei Hauptkategorien unterteilt werden:

  • Class Docstrings: Klasse und Klassenmethoden

  • Package and Module Docstrings: Paket, Module und Funktionen

  • Script Docstrings: Skript und Funktionen

Klasse Docstrings

Klassen-Docstrings werden für die Klasse selbst sowie für alle Klassenmethoden erstellt. Die Dokumentzeichenfolgen werden unmittelbar nach der Klasse oder Klassenmethode platziert, die um eine Ebene eingerückt ist: 

class SimpleClass:
    """Class docstrings go here."""

    def say_hello(self, name: str):
        """Class method docstrings go here."""

        print(f'Hello {name}')

Klassendokumentationszeichenfolgen sollten die folgenden Informationen enthalten:

  • Eine kurze Zusammenfassung seines Zwecks und Verhaltens

  • Alle öffentlichen Methoden, zusammen mit einer kurzen Beschreibung

  • Alle Klasseneigenschaften (Attribute)

  • Alles, was sich auf die Schnittstelle für Unterklassen bezieht, wenn die Klasse für Unterklassen vorgesehen ist

Die Klassenkonstruktorparameter sollten in der Klassenmethode docstring von__init__dokumentiert werden. Einzelne Methoden sollten mit ihren einzelnen Dokumentzeichenfolgen dokumentiert werden. Klassenmethoden-Dokumentzeichenfolgen sollten Folgendes enthalten:

  • Eine kurze Beschreibung der Methode und ihrer Verwendung

  • Alle Argumente (sowohl erforderlich als auch optional), die übergeben werden, einschließlich Schlüsselwortargumenten

  • Beschriften Sie alle Argumente, die als optional gelten oder einen Standardwert haben

  • Alle Nebenwirkungen, die beim Ausführen der Methode auftreten

  • Alle Ausnahmen, die ausgelöst werden

  • Einschränkungen, wann die Methode aufgerufen werden kann

Nehmen wir ein einfaches Beispiel für eine Datenklasse, die ein Tier darstellt. Diese Klasse enthält einige Klasseneigenschaften, Instanzeigenschaften,__init__ und eine einzelne Instanzmethode: 

class Animal:
    """
    A class used to represent an Animal

    ...

    Attributes
    ----------
    says_str : str
        a formatted string to print out what the animal says
    name : str
        the name of the animal
    sound : str
        the sound that the animal makes
    num_legs : int
        the number of legs the animal has (default 4)

    Methods
    -------
    says(sound=None)
        Prints the animals name and what sound it makes
    """

    says_str = "A {name} says {sound}"

    def __init__(self, name, sound, num_legs=4):
        """
        Parameters
        ----------
        name : str
            The name of the animal
        sound : str
            The sound the animal makes
        num_legs : int, optional
            The number of legs the animal (default is 4)
        """

        self.name = name
        self.sound = sound
        self.num_legs = num_legs

    def says(self, sound=None):
        """Prints what the animals name is and what sound it makes.

        If the argument `sound` isn't passed in, the default Animal
        sound is used.

        Parameters
        ----------
        sound : str, optional
            The sound the animal makes (default is None)

        Raises
        ------
        NotImplementedError
            If no sound is set for the animal or passed in as a
            parameter.
        """

        if self.sound is None and sound is None:
            raise NotImplementedError("Silent Animals are not supported!")

        out_sound = self.sound if sound is None else sound
        print(self.says_str.format(name=self.name, sound=out_sound))
Paket- und Modul-Docstrings

Paketdokumentationszeichenfolgen sollten oben in der__init__.py-Datei des Pakets platziert werden. Diese Dokumentzeichenfolge sollte die Module und Unterpakete auflisten, die vom Paket exportiert werden.

Modul-Docstrings ähneln Klassen-Docstrings. Anstatt Klassen und Klassenmethoden zu dokumentieren, ist es jetzt das Modul und alle darin enthaltenen Funktionen. Modul-Dokumentzeichenfolgen werden bereits vor dem Import am Anfang der Datei platziert. Die Modul-Dokumentzeichenfolgen sollten Folgendes enthalten:

  • Eine kurze Beschreibung des Moduls und seines Zwecks

  • Eine Liste aller Klassen, Ausnahmen, Funktionen und sonstigen vom Modul exportierten Objekte

Die Dokumentzeichenfolge für eine Modulfunktion sollte dieselben Elemente wie eine Klassenmethode enthalten:

  • Eine kurze Beschreibung, was die Funktion ist und wofür sie verwendet wird

  • Alle Argumente (sowohl erforderlich als auch optional), die übergeben werden, einschließlich Schlüsselwortargumenten

  • Beschriften Sie alle Argumente, die als optional gelten

  • Alle Nebenwirkungen, die beim Ausführen der Funktion auftreten

  • Alle Ausnahmen, die ausgelöst werden

  • Einschränkungen, wann die Funktion aufgerufen werden kann

Skript-Docstrings

Skripte werden als ausführbare Dateien für einzelne Dateien betrachtet, die von der Konsole ausgeführt werden. Dokumentzeichenfolgen für Skripte befinden sich oben in der Datei und sollten so gut dokumentiert sein, dass Benutzer ein ausreichendes Verständnis für die Verwendung des Skripts haben. Es sollte für die Meldung "Verwendung" verwendet werden können, wenn der Benutzer einen Parameter falsch übergibt oder die Option-hverwendet.

Wenn Sieargparse verwenden, können Sie die parameterbezogene Dokumentation weglassen, vorausgesetzt, sie wurde korrekt im Parameterhelp der Funktionargparser.parser.add_argument dokumentiert. Es wird empfohlen,__doc__ für den Parameterdescription innerhalb des Konstruktors vonargparse.ArgumentParser zu verwenden. In unserem Tutorial zuCommand-Line Parsing Libraries finden Sie weitere Informationen zur Verwendung vonargparse und anderen gängigen Befehlszeilenparsern.

Schließlich sollten benutzerdefinierte Importe oder Importe von Drittanbietern in den Dokumentzeichenfolgen aufgeführt werden, damit Benutzer wissen, welche Pakete möglicherweise zum Ausführen des Skripts erforderlich sind. Hier ist ein Beispiel für ein Skript, mit dem einfach die Spaltenüberschriften einer Tabelle ausgedruckt werden: 

"""Spreadsheet Column Printer

This script allows the user to print to the console all columns in the
spreadsheet. It is assumed that the first row of the spreadsheet is the
location of the columns.

This tool accepts comma separated value files (.csv) as well as excel
(.xls, .xlsx) files.

This script requires that `pandas` be installed within the Python
environment you are running this script in.

This file can also be imported as a module and contains the following
functions:

    * get_spreadsheet_cols - returns the column headers of the file
    * main - the main function of the script
"""

import argparse

import pandas as pd


def get_spreadsheet_cols(file_loc, print_cols=False):
    """Gets and prints the spreadsheet's header columns

    Parameters
    ----------
    file_loc : str
        The file location of the spreadsheet
    print_cols : bool, optional
        A flag used to print the columns to the console (default is
        False)

    Returns
    -------
    list
        a list of strings used that are the header columns
    """

    file_data = pd.read_excel(file_loc)
    col_headers = list(file_data.columns.values)

    if print_cols:
        print("\n".join(col_headers))

    return col_headers


def main():
    parser = argparse.ArgumentParser(description=__doc__)
    parser.add_argument(
        'input_file',
        type=str,
        help="The spreadsheet file to pring the columns of"
    )
    args = parser.parse_args()
    get_spreadsheet_cols(args.input_file, print_cols=True)


if __name__ == "__main__":
    main()

Docstring-Formate

Möglicherweise haben Sie bemerkt, dass in den Beispielen in diesem Lernprogramm bestimmte Formatierungen mit gemeinsamen Elementen vorgenommen wurden:Arguments,Returns undAttributes. Es gibt bestimmte Docstrings-Formate, mit denen Docstring-Parser und Benutzer über ein bekanntes und bekanntes Format verfügen können. Die in den Beispielen in diesem Lernprogramm verwendeten Formatierungen sind Docstrings im NumPy / SciPy-Stil. Einige der gebräuchlichsten Formate sind die folgenden:

Formatierungsart Beschreibung Unterstützt von Sphynx Formale Spezifikation

Google Docstrings

Von Google empfohlene Dokumentationsform

Yes

No

reStructured Text

Offizieller Python-Dokumentationsstandard; Nicht anfängerfreundlich, aber reich an Funktionen

Yes

Yes

NumPy/SciPy docstrings

NumPys Kombination aus reStructured und Google Docstrings

Yes

Yes

Epytext

Eine Python-Adaption von Epydoc; Ideal für Java-Entwickler

Nicht offiziell

Yes

Die Auswahl des Dokumentzeichenfolgenformats liegt bei Ihnen, Sie sollten jedoch in Ihrem gesamten Dokument / Projekt das gleiche Format beibehalten. Im Folgenden finden Sie Beispiele für jeden Typ, um Ihnen eine Vorstellung davon zu geben, wie jedes Dokumentationsformat aussieht.

Beispiel für Google Docstrings 
"""Gets and prints the spreadsheet's header columns

Args:
    file_loc (str): The file location of the spreadsheet
    print_cols (bool): A flag used to print the columns to the console
        (default is False)

Returns:
    list: a list of strings representing the header columns
"""
Beispiel für reStructured Text 
"""Gets and prints the spreadsheet's header columns

:param file_loc: The file location of the spreadsheet
:type file_loc: str
:param print_cols: A flag used to print the columns to the console
    (default is False)
:type print_cols: bool
:returns: a list of strings representing the header columns
:rtype: list
"""
NumPy/SciPy Docstrings Example
"""Gets and prints the spreadsheet's header columns

Parameters
----------
file_loc : str
    The file location of the spreadsheet
print_cols : bool, optional
    A flag used to print the columns to the console (default is False)

Returns
-------
list
    a list of strings representing the header columns
"""
Epytext-Beispiel 
"""Gets and prints the spreadsheet's header columns

@type file_loc: str
@param file_loc: The file location of the spreadsheet
@type print_cols: bool
@param print_cols: A flag used to print the columns to the console
    (default is False)
@rtype: list
@returns: a list of strings representing the header columns
"""

Dokumentieren Sie Ihre Python-Projekte

Python-Projekte gibt es in allen möglichen Formen, Größen und Zwecken. Die Art und Weise, wie Sie Ihr Projekt dokumentieren, sollte Ihrer spezifischen Situation entsprechen. Denken Sie daran, wer die Benutzer Ihres Projekts sein werden, und passen Sie sie an ihre Bedürfnisse an. Je nach Projekttyp werden bestimmte Aspekte der Dokumentation empfohlen. Das allgemeine Layout des Projekts und seiner Dokumentation sollte wie folgt aussehen: 

project_root/
│
├── project/  # Project source code
├── docs/
├── README
├── HOW_TO_CONTRIBUTE
├── CODE_OF_CONDUCT
├── examples.py

Projekte können im Allgemeinen in drei Haupttypen unterteilt werden: Privat, Freigegeben und Öffentlich / Open Source.

Private Projekte

Private Projekte sind Projekte, die nur für den persönlichen Gebrauch bestimmt sind und im Allgemeinen nicht mit anderen Benutzern oder Entwicklern geteilt werden. Die Dokumentation kann für diese Art von Projekten ziemlich leicht sein. Es gibt einige empfohlene Teile, die bei Bedarf hinzugefügt werden müssen:

  • Readme: Eine kurze Zusammenfassung des Projekts und seines Zwecks. Geben Sie spezielle Anforderungen für die Installation oder den Betrieb des Projekts an.

  • examples.py: Eine Python-Skriptdatei, die einfache Beispiele für die Verwendung des Projekts enthält.

Denken Sie daran, auch wenn private Projekte für Sie persönlich bestimmt sind, werden Sie auch als Benutzer betrachtet. Denken Sie an alles, was Sie später verwirren könnte, und stellen Sie sicher, dass Sie diese entweder in Kommentaren, Dokumentzeichenfolgen oder in der Readme-Datei festhalten.

Gemeinsame Projekte

Freigegebene Projekte sind Projekte, bei denen Sie mit einigen anderen Personen bei der Entwicklung und / oder Verwendung des Projekts zusammenarbeiten. Der „Kunde“ oder Benutzer des Projekts ist weiterhin Sie selbst und die wenigen, die das Projekt ebenfalls nutzen.

Die Dokumentation sollte etwas strenger sein als für ein privates Projekt, hauptsächlich um neue Mitglieder in das Projekt einzubeziehen oder Mitwirkende / Benutzer auf neue Änderungen am Projekt aufmerksam zu machen. Einige der empfohlenen Teile, die dem Projekt hinzugefügt werden sollen, sind folgende:

  • Readme: Eine kurze Zusammenfassung des Projekts und seines Zwecks. Geben Sie spezielle Anforderungen für die Installation oder den Betrieb des Projekts an. Fügen Sie außerdem alle wichtigen Änderungen gegenüber der vorherigen Version hinzu.

  • examples.py: Eine Python-Skriptdatei, die einfache Beispiele für die Verwendung der Projekte enthält.

  • How to Contribute: Dies sollte beinhalten, wie neue Mitwirkende am Projekt anfangen können, Beiträge zu leisten.

Öffentliche und Open Source-Projekte

Öffentliche und Open Source-Projekte sind Projekte, die für eine große Gruppe von Benutzern freigegeben werden sollen und an denen große Entwicklungsteams beteiligt sein können. Diese Projekte sollten der Projektdokumentation einen ebenso hohen Stellenwert einräumen wie die eigentliche Entwicklung des Projekts. Einige der empfohlenen Teile, die dem Projekt hinzugefügt werden sollen, sind folgende:

  • Readme: Eine kurze Zusammenfassung des Projekts und seines Zwecks. Geben Sie spezielle Anforderungen für die Installation oder den Betrieb der Projekte an. Fügen Sie außerdem alle wichtigen Änderungen gegenüber der vorherigen Version hinzu. Fügen Sie abschließend Links zu weiterer Dokumentation, Fehlerberichterstattung und anderen wichtigen Informationen für das Projekt hinzu. Dan Bader hata great tutorial zusammengestellt, was alles in Ihrer Readme enthalten sein sollte.

  • How to Contribute: Dies sollte beinhalten, wie neue Mitwirkende am Projekt helfen können. Dies umfasst das Entwickeln neuer Funktionen, das Beheben bekannter Probleme, das Hinzufügen von Dokumentation, das Hinzufügen neuer Tests oder das Melden von Problemen.

  • Code of Conduct: Definiert, wie andere Mitwirkende bei der Entwicklung oder Verwendung Ihrer Software miteinander umgehen sollen. Dies gibt auch an, was passieren wird, wenn dieser Code defekt ist. Wenn Sie Github verwenden, kann ein Verhaltenskodextemplate mit empfohlenem Wortlaut erstellt werden. Erwägen Sie insbesondere für Open Source-Projekte, dies hinzuzufügen.

  • License: Eine Klartextdatei, die die Lizenz beschreibt, die Ihr Projekt verwendet. Erwägen Sie insbesondere für Open Source-Projekte, dies hinzuzufügen.

  • docs: Ein Ordner, der weitere Dokumentation enthält. Im nächsten Abschnitt wird ausführlicher beschrieben, was enthalten sein sollte und wie der Inhalt dieses Ordners organisiert wird.

Die vier Hauptabschnitte des Ordnersdocs

Daniele Procida gab wundervollePyCon 2017 talk und nachfolgendeblog post über die Dokumentation von Python-Projekten. Er erwähnt, dass alle Projekte die folgenden vier Hauptabschnitte haben sollten, damit Sie sich auf Ihre Arbeit konzentrieren können:

  • Tutorials: Lektionen, die den Leser durch eine Reihe von Schritten führen, um ein Projekt (oder eine sinnvolle Übung) abzuschließen. Auf das Lernen der Benutzer ausgerichtet.

  • How-To Guides: Anleitungen, die den Leser durch die Schritte führen, die zur Lösung eines allgemeinen Problems erforderlich sind (problemorientierte Rezepte).

  • References: Erklärungen, die ein bestimmtes Thema verdeutlichen und beleuchten. Auf Verständnis ausgerichtet.

  • Explanations: Technische Beschreibungen der Maschinen und ihrer Bedienung (Schlüsselklassen, Funktionen, APIs usw.). Denken Sie an einen Enzyklopädie-Artikel.

Die folgende Tabelle zeigt, wie sich alle diese Abschnitte zueinander verhalten und welchen allgemeinen Zweck sie haben:

Am nützlichsten, wenn wir studieren Am nützlichsten, wenn wir codieren

Praktischer Schritt

Tutorials

Anleitungen

Theoretisches Wissen

Erläuterung

Referenz

Am Ende möchten Sie sicherstellen, dass Ihre Benutzer Zugriff auf die Antworten auf alle Fragen haben, die sie möglicherweise haben. Wenn Sie Ihr Projekt auf diese Weise organisieren, können Sie diese Fragen einfach beantworten und in einem Format, in dem sie schnell navigieren können.

Dokumentationswerkzeuge und -ressourcen

Das Dokumentieren Ihres Codes, insbesondere großer Projekte, kann entmutigend sein. Zum Glück gibt es einige Tools und Referenzen, die Ihnen den Einstieg erleichtern:

Tool Beschreibung

Sphinx

Eine Sammlung von Tools zum automatischen Generieren von Dokumentation in mehreren Formaten

Epydoc

Ein Tool zum Generieren von API-Dokumentation für Python-Module basierend auf deren Dokumentzeichenfolgen

Lesen Sie die Dokumente

Automatische Erstellung, Versionierung und Hosting Ihrer Dokumente für Sie

Sauerstoff

Ein Tool zum Generieren von Dokumentation, das Python sowie mehrere andere Sprachen unterstützt

MkDocs

Ein statischer Site-Generator zum Erstellen der Projektdokumentation in der Markdown-Sprache

Pycco

Ein "schneller und schmutziger" Dokumentationsgenerator, der Code und Dokumentation nebeneinander anzeigt. Überprüfen Sieour tutorial on how to use it for more info.

Neben diesen Tools gibt es einige zusätzliche Tutorials, Videos und Artikel, die bei der Dokumentation Ihres Projekts hilfreich sein können:

  1. Carol Willing - Praktische Sphinx - PyCon 2018

  2. Daniele Procida - Dokumentationsgetriebene Entwicklung - Lehren aus dem Django-Projekt - PyCon 2016

  3. Eric Holscher - Dokumentieren Sie Ihr Projekt mit Sphinx & Read the Docs - PyCon 2016

  4. Titus Brown, Luiz Irber - Erstellen, Erstellen, Testen und Dokumentieren eines Python-Projekts: ein praktisches HOWTO - PyCon 2016

  5. Offizielle Dokumentation des umstrukturierten Textes

  6. Sphinx 'reStructured Text Primer

Manchmal ist der beste Weg zu lernen, andere nachzuahmen. Hier sind einige großartige Beispiele für Projekte, bei denen die Dokumentation gut verwendet wird:

Wo soll ich anfangen?

Die Dokumentation von Projekten verläuft einfach:

  1. Keine Dokumentation

  2. Einige Dokumentationen

  3. Vollständige Dokumentation

  4. Gute Dokumentation

  5. Großartige Dokumentation

Wenn Sie nicht wissen, wohin Sie mit Ihrer Dokumentation als Nächstes gehen sollen, überprüfen Sie, wo sich Ihr Projekt jetzt in Bezug auf den obigen Fortschritt befindet. Haben Sie Unterlagen? Wenn nicht, dann fangen Sie dort an. Wenn Sie über eine Dokumentation verfügen, aber einige der wichtigsten Projektdateien fehlen, fügen Sie diese zunächst hinzu.

Lassen Sie sich am Ende nicht entmutigen oder überfordern, wie viel Arbeit für die Dokumentation von Code erforderlich ist. Sobald Sie mit der Dokumentation Ihres Codes beginnen, wird es einfacher, weiterzumachen. Sie können gerne Kommentare abgeben, wenn Sie Fragen haben oder sich in den sozialen Medien an das Real Python-Team wenden. Wir helfen Ihnen dabei.

Related