Kurs Python · Moduł 12: Projekt końcowy

Dokumentacja Techniczna

5 min czytania ·
W tej lekcji3

Najlepszy przewodnik po sawannie jest bezużyteczny, jeśli jego wiedza znika razem z nim. Nowy członek ekspedycji dostaje wtedy tylko kopię tropów bez legendy. Z kodem jest tak samo: projekt bez dokumentacji umie uruchomić jedna osoba, a po trzech miesiącach nawet ona zapomina, jak to robiła. Dokumentacja to most między kodem a ludźmi. Dobra dokumentacja sprawia, że projekt żyje nawet wtedy, gdy Ty śpisz, a rekruter albo nowy współpracownik rozumie go w pięć minut.

Dokumentację budujemy na trzech poziomach: README dla człowieka, który widzi repozytorium pierwszy raz, docstringi dla osoby czytającej kod oraz automatyczna dokumentacja API dla tych, którzy z niego korzystają. Dobra kolejność pracy to najpierw README, potem docstringi, potem konfiguracja generowanej dokumentacji API, a na koniec CHANGELOG.md, czyli dziennik zmian w kolejnych wersjach.

README.md - wizytówka projektu

README to pierwsza rzecz, którą GitHub pokazuje pod listą plików. Typowa kolejność sekcji: tytuł, opis lub funkcje, szybki start, a na końcu licencja. Oto kompletny przykład dla naszego asystenta:

# AI Document Assistant

Inteligentny asystent do przeszukiwania dokumentów wykorzystujący RAG.

## Funkcje

- Semantic search w dokumentach
- Odpowiedzi w języku naturalnym
- Obsługa PDF, DOCX, TXT
- Szybkie odpowiedzi (<2s)

## Quick Start

### Wymagania
- Python 3.12+
- Docker (dla Qdrant)

### Instalacja

```bash
# Klonuj repo
git clone https://github.com/user/ai-doc-assistant.git
cd ai-doc-assistant

# Utwórz środowisko
python -m venv venv
source venv/bin/activate

# Zainstaluj zależności
pip install -r requirements.txt

# Uruchom Qdrant
docker compose up -d qdrant

# Ustaw zmienne środowiskowe
cp .env.example .env
# Edytuj .env i dodaj OPENAI_API_KEY

# Uruchom aplikację
uvicorn app.main:app --reload
```

## API Documentation

Po uruchomieniu: http://localhost:8000/docs

## Architecture

[Link do diagramu architektury]

## Testing

```bash
pytest tests/ -v
```

## License

MIT

Instrukcja instalacji to kolejne polecenia, które da się skopiować i uruchomić: klon, wirtualne środowisko, zależności, baza, zmienne środowiskowe, start. Zwróć uwagę na cp .env.example .env: prawdziwe klucze nigdy nie trafiają do repozytorium, tylko wzór pliku. docker compose (ze spacją) to obecna wersja narzędzia, wbudowana w Dockera jako plugin.

Docstrings - dokumentacja w kodzie

Docstring to napis w potrójnych cudzysłowach zaraz pod definicją klasy lub funkcji. PEP 257 opisuje ogólne konwencje, a sam format sekcji wybierasz. Najpopularniejsze są Google style i NumPy style, oba czytane przez Sphinx (rozszerzenie napoleon). My używamy Google style: sekcje Attributes, Args, Returns, Raises i Example.

from typing import Optional

class RAGService:
    """
    Serwis RAG do odpowiadania na pytania na podstawie dokumentów.

    Ten serwis implementuje pełny pipeline RAG:
    1. Embedding pytania
    2. Wyszukiwanie podobnych dokumentów
    3. Generowanie odpowiedzi z kontekstem

    Attributes:
        vector_store: Klient do vector database
        llm: Klient do modelu językowego
        embedder: Serwis do tworzenia embeddingów

    Example:
        >>> service = RAGService(vector_store, llm, embedder)
        >>> response = await service.query("Co to jest Python?")
        >>> print(response.answer)
        Python to język programowania...
    """

Docstring klasy mówi, co serwis robi i z czego się składa. Przykład w formacie >>> pokazuje użycie, a linia pod nim to wypisany wynik. Konstruktor jest prosty i nie wymaga osobnego opisu:

    def __init__(
        self,
        vector_store: VectorStore,
        llm: LLMClient,
        embedder: EmbeddingService
    ):
        self.vector_store = vector_store
        self.llm = llm
        self.embedder = embedder

Typy argumentów (VectorStore, LLMClient, EmbeddingService) to interfejsy z warstwy infrastruktury, zgodnie z architekturą z poprzedniej lekcji. Najwięcej opisu wymaga metoda publiczna:

    async def query(
        self,
        question: str,
        top_k: int = 5,
        filters: Optional[dict] = None
    ) -> Response:
        """
        Wykonuje zapytanie RAG.

        Args:
            question: Pytanie użytkownika w języku naturalnym
            top_k: Liczba dokumentów do pobrania (default: 5)
            filters: Opcjonalne filtry metadanych

        Returns:
            Response: Obiekt zawierający odpowiedź i źródła

        Raises:
            ValueError: Gdy pytanie jest puste
            LLMError: Gdy wystąpi błąd generowania

        Example:
            >>> response = await service.query(
            ...     "Jak działa RAG?",
            ...     top_k=3,
            ...     filters={"category": "ai"}
            ... )
        """
        if not question.strip():
            raise ValueError("Question cannot be empty")

        # Implementation...

Sekcja Raises jest często pomijana, a to ona mówi, co może pójść źle. Docstring możesz odczytać w konsoli przez help(RAGService.query), więc to dokumentacja, która zawsze jest pod ręką. Uwaga: przykład z await służy do czytania, zwykły doctest go nie uruchomi.

API Documentation z FastAPI

FastAPI generuje dokumentację API w standardzie OpenAPI (dawniej Swagger) automatycznie, na podstawie typów i modeli Pydantic. Najpierw metadane aplikacji:

from fastapi import FastAPI, HTTPException
from pydantic import BaseModel, Field

app = FastAPI(
    title="AI Document Assistant API",
    description="REST API dla inteligentnego asystenta dokumentów",
    version="1.0.0",
    docs_url="/docs",
    redoc_url="/redoc"
)

Pod /docs dostajesz interaktywne Swagger UI, pod /redoc alternatywny widok ReDoc. Teraz modele żądania i odpowiedzi. Pydantic waliduje dane, a Field dodaje ograniczenia i opisy:

class QueryRequest(BaseModel):
    """Request do zapytania RAG."""
    question: str = Field(
        ...,
        description="Pytanie w języku naturalnym",
        examples=["Co to jest machine learning?"]
    )
    top_k: int = Field(
        default=5,
        ge=1,
        le=20,
        description="Liczba dokumentów źródłowych"
    )

class QueryResponse(BaseModel):
    """Odpowiedź z systemu RAG."""
    answer: str = Field(description="Wygenerowana odpowiedź")
    sources: list[dict] = Field(description="Dokumenty źródłowe")
    latency_ms: float = Field(description="Czas odpowiedzi w ms")

ge=1, le=20 oznacza "od 1 do 20", więc top_k=50 zostanie odrzucone z błędem 422, zanim trafi do Twojego kodu. Przykładowe wartości podajemy przez examples=[...]. Stary parametr example= jest w Pydantic v2 przestarzały i generuje ostrzeżenie. Na koniec endpoint:

@app.post(
    "/query",
    response_model=QueryResponse,
    summary="Zadaj pytanie",
    description="Wykonuje zapytanie RAG i zwraca odpowiedź z źródłami"
)
async def query(request: QueryRequest) -> QueryResponse:
    """
    Endpoint do zadawania pytań systemowi RAG.

    - **question**: Pytanie w języku naturalnym
    - **top_k**: Liczba dokumentów do przeszukania
    """
    pass

summary i description pojawią się w Swagger UI, a docstring z markdownem również. Nie piszesz żadnego osobnego pliku dokumentacji, schemat powstaje z kodu, więc nie rozjedzie się z rzeczywistością.

Moja rada: pisz README w tym samym dniu, w którym zakładasz repozytorium, a nie na końcu projektu. Dokumentacja pisana na bieżąco jest krótsza i prawdziwsza. W następnej lekcji przejdziemy do deploymentu.

Pamiętaj: dokumentacja to dziennik ekspedycji, dzięki któremu następna wyprawa pójdzie Twoimi tropami bez zgadywania.

Hasła z dokumentacji w tej lekcji

Widzisz błąd w tej lekcji?

Sprawdź się

Odpowiedz na pytania z tej lekcji. Wybierz odpowiedź, a od razu zobaczysz, czy jest poprawna.

  1. 1. Który styl docstringów jest zalecany dla Pythona?

  2. 2. Który standard jest używany do dokumentacji REST API w Pythonie?

Zadania praktyczne w grze

  • Edytor kodu

    Stwórz profesjonalny docstring

  • Układanie w pionie

    Uporządkuj kroki:

  • Układanie w poziomie

    Ułóż typowe sekcje README.md:

  1. PytanieDocstrings
  2. PytanieAPI Documentation
  3. Zadanie z kodemDocstring dla klasy
  4. Ułóż w kolejnościDokumentowanie projektu
  5. Ułóż w kolejnościREADME sections

Przydatne artykuły