Создание документации для библиотек Python: методы и инструменты

Раздел: Обучение Python -> Документация и справка

Основные способы документирования Python библиотек

Современный подход: Sphinx с автоматической сборкой документации

Sphinx - это основной инструмент для создания документации Python проектов. Он поддерживает reStructuredText и Markdown, генерирует HTML, PDF, ePub. Для подключения докстрингов из кода используется расширение autodoc.

Как создать документацию библиотеки с помощью Sphinx, используя докстринги из исходного кода?

  1. Установите Sphinx и автодок: 
    pip install sphinx sphinx-autodoc

    Python документация библиотек (документация библиотек python)

  2. Инициализируйте проект: 
    sphinx-quickstart
    Ответьте на вопросы (разделите исходники и документацию).
  3. Настройте conf.py: укажите путь к модулям и подключите расширения: 
    
import os
import sys
sys.path.insert(0, os.path.abspath('../src'))
extensions = ['sphinx.ext.autodoc', 'sphinx.ext.napoleon']
  4. Создайте файл .rst для описания вашего модуля, используя директивы autodoc: 
    
.. automodule:: mymodule
   :members:
   :undoc-members:
   :show-inheritance:
  5. Сгенерируйте HTML: 
    make html

Типичная ошибка:

Модуль не найден - ImportError: No module named 'mymodule'.

Решение: проверьте путь sys.path в conf.py. Убедитесь, что модуль установлен или находится в указанном каталоге.

Цель: создание полноценной документации с перекрёстными ссылками, поиском и автоматическим извлечением сигнатур функций.

Как получить документацию прямо из интерпретатора без установки дополнительных пакетов?

Используйте встроенный help() и атрибут __doc__.


def add(a: int, b: int) -> int:
    """Складывает два целых числа."""
    return a + b

print(add.__doc__)        # Складывает два целых числа.
help(add)                 # Покажет справку с сигнатурой и докстрингом.

Проблема:

Докстринг не отображается, если модуль загружен динамически или содержит только комментарии (#).

Решение: всегда используйте тройные кавычки внутри функции/класса/модуля.

Случай использования: быстрая проверка документации во время разработки.

Как сгенерировать HTML документацию одной командой без сложной настройки?

Утилита pydoc создаёт простую веб-страницу из докстрингов модуля.


python -m pydoc -w mymodule   # создаёт mymodule.html

Для запуска сервера: 

python -m pydoc -p 8080

Ошибка: pydoc не обрабатывает аннотации типов нового стиля (list[int]), если Python < 3.9.

Решение: обновите Python или используйте Sphinx.

Случай использования: быстрая документация для небольшого скрипта или модуля.

Как использовать MkDocs для документации Python библиотеки с Markdown?

MkDocs подходит для проектов, где документация пишется вручную в Markdown.

  1. Установка: 
    pip install mkdocs mkdocstrings
  2. Создание проекта: 
    mkdocs new mydocs
  3. Настройка mkdocs.yml для автодока: 
    
site_name: My Library Docs
plugins:
  - mkdocstrings
  4. В Markdown файле используйте: ::: mymodule.MyClass
  5. Сборка: 
    mkdocs build

Проблема: mkdocstrings не находит модуль из-за неправильного пути.

Решение: укажите путь в PYTHONPATH или настройте watch в mkdocs.yml.

Случай использования: проекты, где команда предпочитает Markdown reStructuredText.

Как встроить тесты документации с помощью doctest?

doctest позволяет запускать примеры из докстрингов как тесты.


def multiply(a, b):
    """
    >>> multiply(2, 3)
    6
    >>> multiply('a', 3)
    'aaa'
    """
    return a * b

if __name__ == '__main__':
    import doctest
    doctest.testmod()

Ошибка: примеры не проходят из-за неточного форматирования вывода (пробелы, типы).

Решение: используйте # doctest: +NORMALIZE_WHITESPACE или # doctest: +ELLIPSIS для неточного совпадения.

Случай использования: гарантия актуальности примеров в документации.

Расширенные примеры оформления документации

Пример 1. Sphinx с автодокументированием класса в стиле Google

Код модуля calculator.py:

Пример 

class Calculator:
    """Класс для выполнения базовых математических операций.

    Args:
        name (str): Название калькулятора (необязательно, по умолчанию "Calc").

    Attributes:
        history (list): Список выполненных операций.
    """

    def __init__(self, name: str = "Calc"):
        self.name = name
        self.history = []

    def add(self, a: float, b: float) -> float:
        """Сложение двух чисел.

        Args:
            a: Первое слагаемое.
            b: Второе слагаемое.

        Returns:
            Сумма a и b.

        Examples:
            >>> calc = Calculator()
            >>> calc.add(3, 4)
            7.0
        """
        result = a + b
        self.history.append(('add', result))
        return float(result)

Файл index.rst с директивой autoclass:

Пример 

Calculator API
==============

.. autoclass:: calculator.Calculator
   :members:
   :undoc-members:
   :inherited-members:

Результат сборки Sphinx:

Calculator класс
----------------
Класс для выполнения базовых математических операций.

Параметры конструктора:
 - name (str) – Название калькулятора (по умолчанию "Calc").

Атрибуты:
 - history (list) – Список выполненных операций.

add(a, b) -> float
    Сложение двух чисел.
    ...

Пример 2. Интеграция с Read the Docs

Файл .readthedocs.yml для автоматической сборки:

Пример 

version: 2

build:
  os: ubuntu-22.04
  tools:
    python: "3.11"

sphinx:
  configuration: docs/conf.py
  builder: html

python:
  install:
    - method: pip
      path: .
      extra_requirements:
        - docs

requirements.txt для документации:

Пример 

sphinx==7.2.6
sphinx-rtd-theme==1.3.0
sphinx-autodoc==1.2.0

Пример 3. Использование Napoleon для форматов Google/NumPy

В conf.py подключите расширение Napoleon:

Пример 

extensions = ['sphinx.ext.napoleon']
napoleon_google_docstring = True
napoleon_numpy_docstring = True
napoleon_include_init_with_doc = True

Пример докстринга в стиле NumPy:

Пример 

def matrix_multiply(A: np.ndarray, B: np.ndarray) -> np.ndarray:
    """
    Умножает две матрицы.

    Parameters
    ----------
    A : numpy.ndarray
        Первая матрица (m x n).
    B : numpy.ndarray
        Вторая матрица (n x p).

    Returns
    -------
    numpy.ndarray
        Произведение матриц размерностью (m x p).

    Raises
    ------
    ValueError
        Если число столбцов A не равно числу строк B.
    """
    ...

Пример 4. Динамическая документация с MkDocs и mkdocstrings

Структура проекта:

Пример 

project/
├── src/
│   └── mylib.py
├── docs/
│   ├── index.md
│   └── api.md
├── mkdocs.yml
└── requirements.txt

Файл mkdocs.yml:

Пример 

site_name: MyLib Documentation
nav:
  - Главная: index.md
  - API: api.md
plugins:
  - mkdocstrings:
      handlers:
        python:
          paths: [src]
          options:
            show_source: true

Файл api.md:

Пример 

# API Reference

::: mylib.MyClass
    rendering:
      show_root_heading: true
      show_root_full_path: false

Результат сборки mkdocs build – HTML страница с автоматически извлечённой документацией класса MyClass и его методов.

Документация библиотек Python - comments

En
Python документация библиотек (python)