Primii pași cu pdoc3 pentru Python

  • 3 minute de citit
  • 6 exemple de cod în Python și Shell
  • 3 imagini

Disponibil și în English

Salut tuturor! 👋

În acest articol vorbim despre documentație și despre cum să documentezi un proiect Python cu pdoc.

pdoc-feature

Documentația este o parte esențială a scrierii codului Python de calitate. Nu doar că îl face mai ușor de înțeles, dar îl face și mai ușor de întreținut și de refolosit. În acest articol, vom explora cum să folosim pdoc pentru a genera documentație pentru codul tău Python.

pdoc este un instrument puternic care poate genera automat documentație pentru modulele și clasele tale Python, pe baza docstring-urilor. Docstring-urile sunt șiruri speciale care apar la începutul unui modul, al unei funcții sau al unei clase și oferă o descriere a scopului obiectului, a parametrilor, a valorilor returnate și a altor informații relevante.

Iată un exemplu de docstring pentru o funcție Python simplă:

def greet(name: str) -> str:    """    Return a personalized greeting message.    Parameters    ----------    name : str        The name of the person to greet.    Returns    -------    str        A greeting message addressed to the specified person.    """    return f"Hello, {name}!"

În exemplul de mai sus, docstring-ul funcției greet include o scurtă descriere a scopului său, precum și informații despre parametrul și valoarea returnată.

Pentru a genera documentație pentru această funcție cu pdoc, ar trebui mai întâi să instalezi pdoc folosind pip:

pip install pdoc

Odată instalat, poți genera documentație HTML pentru codul tău Python folosind comanda pdoc:

pdoc --html mymodule.py

Aceasta va genera un set de fișiere HTML într-un director numit mymodule.html, pe care le poți vizualiza apoi într-un browser web.

Implicit, pdoc va folosi formatul de docstring în stilul Google, care folosește ghilimele triple pentru a încadra docstring-urile și include secțiuni pentru Args, Returns și Raises. Totuși, poți personaliza și formatul docstring-urilor tale, în funcție de nevoile tale.

De exemplu, iată o altă modalitate de a documenta funcția greet, folosind un format de docstring mai concis:

def greet(name: str) -> str:    """    Return a personalized greeting message.    name: str        The name of the person to greet.    Returns:        A greeting message addressed to the specified person.    """    return f"Hello, {name}!"

În acest format, parametrii funcției și valoarea returnată sunt descriși folosind o sintaxă simplă, separată prin două puncte.

În final, merită menționat că pdoc poate genera documentație și pentru clase, precum și pentru alte tipuri de obiecte Python, cum ar fi module și pachete. Iată un exemplu de docstring pentru o clasă Python simplă:

class Person:"""A simple class representing a person.    Attributes    ----------    name : str        The person's name.    age : int        The person's age.    """    def __init__(self, name: str, age: int):        self.name = name        self.age = age

În exemplul de mai sus, docstring-ul clasei Person include o scurtă descriere a scopului său, precum și informații despre atributele sale.

Un exemplu mai complet ar arăta astfel

pdoc-code

Iar codul:

def run_binary(binary_path: str) -> None:    """    Run a binary.    Parameters    ----------    binary_path : str        The directory path that contains the binary name.    Raises    ------    FileNotFoundError        If the binary file is not found.    RuntimeError        If the binary returns a non-zero exit code.    Notes    -----    This function assumes that the binary file is executable.    Examples    --------    >>> run_binary('/usr/local/bin/')    """    # Function code here

În exemplul de mai sus, docstring-ul funcției run_binary include următoarele câmpuri:

  • Parameters: Parametrii funcției, inclusiv tipurile și descrierile lor.
  • Returns: Valoarea returnată de funcție, inclusiv tipul și descrierea ei (în acest caz, None).
  • Raises: Excepțiile pe care le poate ridica funcția, inclusiv numele și descrierile lor.
  • Notes: Note suplimentare despre funcție, care pot fi utile cititorului.
  • Examples: Exemple de utilizare a funcției, inclusiv intrările și ieșirile așteptate.

Documentația generată va arăta astfel:

pdoc-example

În concluzie, documentarea codului Python este o parte importantă a procesului de dezvoltare software, iar pdoc poate face mai ușor ca niciodată generarea de documentație de calitate pentru modulele, clasele și funcțiile tale.

Mulțumesc pentru lectură! 📚