sphinx – jak generować dokumentacje z projektu w Python’ie #3: Nagłówki

Dokumentacja powinna opisywać funkcje, metody i klasy w sposób łatwy do zrozumienia. Sphinx pozwala uporządkować różne sekcje naszego kodu odpowiednimi nagłówkami.

InstalacjaJak pisać czytelny brief​Instalacja

W zależności od złożoności zapisywanej funkcji, metody lub klasy, jednowierszowy dockstring może nie być całkowicie wystarczający. Używamy takiego zapisu tylko w naprawdę oczywistych przypadkach, takich jak:

def simple_method():
    """This is simple method which returns True"""
    return True

Dokument powinien opisywać funkcję w sposób łatwy do zrozumienia, w prostych przypadkach, takich jak trywialne funkcje i klasy,  dodanie podpisu funkcji (np. simple_method() -> wynik) wystarczy jednolinijkowy opis, wynika to z faktu, że dzięki inspekcji Pythona sphinx’em można łatwo znaleźć te informacje w razie potrzeby w dokumentacji, a także łatwo je odczytać, czytając kod źródłowy.

Jednak w większych lub bardziej złożonych projektach często dobrym pomysłem jest podanie dodatkowych informacji o danej części kodu (np. funkcji), jej działaniu, ewentualnych wyjątkach, zwracanych wartościach, istotnych szczegółach dotyczących parametrów, lub potrzebnej refaktoryzacji istniejącego kodu.

def simple_method(arg1: int, arg2: int) -> bool:
    """ Method example
 
 
    Args:
    arg1 (int): Int argument one
    arg2 (int): Int argument two
    Returns:
    bool: return True
 
 
    """
    return True

Sekcje Docstring’ów

Obsługiwane są wszystkie następujące nagłówki sekcji: 

Najczęściej używanymi nagłówkami są Args, Return, Todo, Raises. Chciałbym, przybliżyć czym są:

1. Zaczynając od „Args”, oznacza on argumenty metody. Najpierw podajemy ich nazwę, następnie opcjonalnie w nawiasie typ wprowadzanego argumentu, kolejno dwukropek „:” i zaraz po nim opis tego argumentu. Opisujemy argumenty jeden pod drugim. Gdy już wiemy co mamy wprowadzić, czas teraz opisać co będzie zwracane.
2. Nagłówek „Returns” jasno definiuje, co otrzymamy po użyciu danej metody. Pod nagłówkiem wpisz typ – np. bool:, następnie opis zwracanych wartości.
3. Mniej spotykany, ale też często używany jest nagłówek „Todo” – oznacza on rzeczy, które jeszcze mają być wykonane w ramach opisywanej części kodu. Zaraz pod nim wypunktuj je. Każdy kolejny element zaczyna się od gwiazdki „*„.
4. W części „Raises” opisujemy błędy, które są tworzone w ramach metody. Pod nagłówkiem dodajmy nazwę wyjątku, dwukropek „:„, i opis błędu a poniżej krótka prezentacja jak ich użyć:

def simple_method(arg1: int, arg2: int) -> bool:
    """ Method example
 
    Todo:
    * Do something
    * Change something
 
    Args:
        arg1 (int): Int argument one
        arg2 (int): Int argument two
    Returns:
        bool: return True
 
 
    Raises:
        ValueError: Cannot open file
 
    """
    try:
        open(arg1)
    except ValueError as e:
        print(f"Error: {e}")
    return True

Często metody lub klasy bywają przytłaczające ilością zawierającego kodu, w taki sposób bez wdrażania się w kod możemy dokładnie stwierdzić, o co w nim chodzi. Tak wygląda powyższa metoda po jej wygenerowaniu komendą make html:

Tak przygotowani możecie śmiało ruszać w wir pisania kodu, setek klas i metod, z których następnie automatycznie stworzycie obszerną, czytelną a co najważniejsze pomocną dokumentację.

Oczywiście wykresy mogą wyglądać dużo ciekawiej i być bardziej skomplikowane niż na powyższych rysunkach, ale o tym w kolejnych odsłonach serii Python matplotlib.pyplot – jak generować wykresy?

Please leave this field empty

Newsletter

Imię

Adres email *

Sprawdź swoją skrzynkę odbiorczą (albo katalog na spam) i potwierdź swoją subskrypcję.