Living Documentation: Автоматическая Генерация Документации из Кода и Тестов

# Пример: GitHub Actions workflow для генерации документации
name: Generate Living Documentation

on:
  push:
    branches: [main, develop]
  pull_request:
    branches: [main]

jobs:
  generate-docs:
    runs-on: ubuntu-latest

    steps:
      - uses: actions/checkout@v3

      - name: Настроить Python
        uses: actions/setup-python@v4
        with:
          python-version: '3.11'

      - name: Установить зависимости
        run: |
          pip install sphinx sphinx-rtd-theme
          pip install -r requirements.txt

      - name: Генерировать API docs с Sphinx
        run: |
          cd docs
          sphinx-apidoc -f -o source/api ../src
          make html

      - name: Запустить BDD тесты и генерировать отчеты Cucumber
        run: |
          pytest --cucumber-json=cucumber.json
          node generate-cucumber-report.js

      - name: Генерировать спецификацию OpenAPI
        run: |
          python generate_openapi.py > openapi.yaml

      - name: Развернуть документацию
        uses: peaceiris/actions-gh-pages@v3
        with:
          github_token: ${{ secrets.GITHUB_TOKEN }}
          publish_dir: ./docs/_build/html

from fastapi import FastAPI, HTTPException
from pydantic import BaseModel, Field
from typing import List, Optional
from enum import Enum

app = FastAPI(
    title="E-commerce API",
    description="API для управления продуктами, заказами и клиентами",
    version="2.0.0",
    docs_url="/api/docs",
    redoc_url="/api/redoc"
)

class ProductCategory(str, Enum):
    """Перечисление категорий продуктов"""
    ELECTRONICS = "electronics"
    CLOTHING = "clothing"
    BOOKS = "books"

class Product(BaseModel):
    """Модель продукта с валидацией"""
    id: Optional[int] = Field(None, description="Уникальный идентификатор продукта")
    name: str = Field(..., min_length=1, max_length=200, description="Название продукта")
    description: str = Field(..., description="Подробное описание продукта")
    price: float = Field(..., gt=0, description="Цена продукта в USD")
    category: ProductCategory = Field(..., description="Категория продукта")
    in_stock: bool = Field(True, description="Статус наличия")

    class Config:
        schema_extra = {
            "example": {
                "id": 123,
                "name": "Laptop Pro 15",
                "description": "Высокопроизводительный ноутбук с 16GB RAM",
                "price": 1299.99,
                "category": "electronics",
                "in_stock": True
            }
        }

@app.get(
    "/products",
    response_model=List[Product],
    summary="Список всех продуктов",
    description="Получить пагинированный список всех продуктов в каталоге",
    response_description="Список продуктов с метаданными пагинации"
)
async def list_products(
    skip: int = Field(0, ge=0, description="Количество записей для пропуска"),
    limit: int = Field(10, ge=1, le=100, description="Максимум записей для возврата"),
    category: Optional[ProductCategory] = Field(None, description="Фильтр по категории")
):
    """
    Список продуктов с опциональной фильтрацией.

    - **skip**: Смещение пагинации (по умолчанию: 0)
    - **limit**: Размер страницы, макс 100 (по умолчанию: 10)
    - **category**: Опциональный фильтр категории

    Возвращает список продуктов, соответствующих критериям.
    """
    pass

@app.post(
    "/products",
    response_model=Product,
    status_code=201,
    summary="Создать новый продукт",
    description="Добавить новый продукт в каталог",
    responses={
        201: {"description": "Продукт успешно создан"},
        400: {"description": "Некорректные данные продукта"},
        409: {"description": "Продукт уже существует"}
    }
)
async def create_product(product: Product):
    """
    Создать новый продукт в каталоге.

    Обязательные поля:
    - name: Название продукта (1-200 символов)
    - description: Подробное описание
    - price: Цена в USD (должна быть положительной)
    - category: Один из: electronics, clothing, books

    Возвращает созданный продукт с назначенным ID.
    """
    pass

# features/checkout.feature
Feature: Процесс Оформления Заказа
  Как клиент
  Я хочу завершить покупки через оптимизированный процесс оформления
  Чтобы я мог быстро и безопасно покупать товары

  Background:
    Given каталог продуктов содержит:
      | id | name           | price  | stock |
      | 1  | Laptop Pro 15  | 1299.99| 10    |
      | 2  | Беспроводная Мышь | 29.99  | 50    |
    And я вошел как "john@example.com"

  @critical @payment
  Scenario: Успешная оплата кредитной картой
    Given я добавил следующие товары в корзину:
      | product_id | quantity |
      | 1          | 1        |
      | 2          | 2        |
    When я перехожу к оформлению
    And я ввожу адрес доставки:
      | field       | value              |
      | street      | Главная ул. 123    |
      | city        | Москва             |
      | state       | Московская обл.    |
      | postal_code | 101000             |
    And я выбираю метод доставки "Стандартная Доставка"
    And я оплачиваю кредитной картой
    Then заказ должен быть подтвержден
    And я должен получить email подтверждения
    And общая сумма списания должна быть $1,369.97
    And моя корзина должна быть пустой

class PaymentProcessor:
    """
    Обрабатывает платежи для различных методов оплаты.

    Этот класс предоставляет унифицированный интерфейс для обработки платежей
    через различные провайдеры (Stripe, PayPal и др.).

    Attributes:
        provider (str): Название провайдера платежного шлюза
        api_key (str): Ключ аутентификации для провайдера
        timeout (int): Таймаут запроса в секундах

    Example:
        >>> processor = PaymentProcessor('stripe', api_key='sk_test_...')
        >>> result = processor.charge(amount=99.99, currency='USD')
        >>> print(result.status)
        'succeeded'
    """

    def charge(self, amount, currency, card_token, idempotency_key=None):
        """
        Списать средства с метода оплаты.

        Args:
            amount (float): Сумма для списания в указанной валюте
            currency (str): Трехбуквенный код валюты ISO
            card_token (str): Токенизированный идентификатор карты
            idempotency_key (str, optional): Уникальный ключ для предотвращения дублированных списаний

        Returns:
            PaymentResult: Объект содержащий детали транзакции

        Raises:
            InvalidAmountError: Если сумма отрицательная или ноль
            CardDeclinedError: Если платеж отклонен эмитентом
            NetworkError: Если не удалось подключиться к провайдеру
        """
        pass

# ADR-005: Принять Подход Living Documentation

## Статус
Принят

## Контекст
Наша команда борется с документацией, которая быстро устаревает.
Разработчики редко обновляют документы после изменений кода.

## Решение
Мы примем принципы Living Documentation:
1. Генерировать API документацию из аннотаций кода
2. Использовать BDD сценарии как исполняемую документацию
3. Автогенерировать отчеты тестирования в CI/CD pipeline
4. Хранить ADRs в системе контроля версий

## Последствия

### Положительные
- Документация всегда отражает текущую реализацию
- Снижение ручного обслуживания
- Единственный источник истины (код)
- Документация становится проверяемой

### Отрицательные
- Начальные усилия по настройке инструментов
- Команде необходимо обучение

# tests/test_documentation.py
import pytest
from pathlib import Path
import re

def test_all_code_examples_are_valid():
    """Убедиться, что все примеры кода Python синтаксически корректны"""
    docs_path = Path("docs")

    for doc_file in docs_path.rglob("*.md"):
        content = doc_file.read_text()
        code_blocks = re.findall(r'```python\n(.*?)\n```', content, re.DOTALL)

        for i, code in enumerate(code_blocks):
            try:
                compile(code, f'{doc_file}:block-{i}', 'exec')
            except SyntaxError as e:
                pytest.fail(f"Некорректный Python код в {doc_file}: {e}")

def test_api_endpoints_documented():
    """Убедиться, что все API эндпоинты имеют OpenAPI документацию"""
    from app import app

    openapi = app.openapi()
    documented = set(openapi['paths'].keys())
    actual = {route.path for route in app.routes if hasattr(route, 'path')}

    undocumented = actual - documented
    assert not undocumented, f"Эндпоинты без документации: {undocumented}"