Автостопом по Python

Документация к библиотеке Tablib в формате Sphinx

Документация Tablib (http://docs.python-tablib.org/) содержит хороший пример использования Sphinx (http://www.sphinx-doc.org/en/stable/tutorial.html), поскольку это маленькая библиотека, которая применяет много расширений для Sphinx.

Документация к текущей версии Sphinx находится на странице документации Tablib (http://docs.python-tablib.org/). Если вы хотите построить документацию самостоятельно (пользователям Windows понадобится команда male — она старая, но работает как надо), сделайте следующее:

(venv)$ pip install sphinx

(venv)$ cd docs

(venv)$ make html

(venv)$ open _build/html/index.html # Для просмотра результата.

Sphinx предоставляет несколько вариантов тем оформления (http://www.sphinx-doc.org/en/stable/theming.html), которые настраиваются с помощью стандартных шаблонов представления кода и стилей CSS. Шаблоны Tablib для левой боковой панели находятся в каталоге docs/_templates/ в файле basic/layout.html. Вы можете найти этот файл в папке стилей Sphinx, введя в командной строке следующую команду:

(venv)$ python — c 'import sphinx.themes;print(sphinx.themes.__path__)'

Продвинутые пользователи также могут выполнять поиск в docs/_themes/kr/, пользовательском стиле, который расширяет базовую структуру. Его можно выбрать, добавив каталог _themes/ в системный путь, установив необходимые значения свойствам html_theme_path = ['_themes'] и html_theme = 'kr' в docs/conf.py.

Для включения в ваш код документации API, которая генерируется автоматически на основе строк документации, используйте autoclass::. Вам нужно скопировать форматирование строк документации в Tablib, чтобы это сработало:

.. autoclass:: Dataset

····:inherited-members:

Для получения этой функциональности следует ответить «да» на вопрос о включении расширения Sphinx autodoc при запуске sphinx-quickstart, чтобы создать новый проект Sphinx. Директива: inherited-members: также добавит документацию для атрибутов, унаследованных от классов-предков.

Примеры из структуры Tablib

Главная особенность, которую мы хотим подчеркнуть в Tablib, — отсутствие использования классов в модулях в tablib/formats/ (это идеально иллюстрирует наше утверждение, что не нужно везде применять классы). Далее мы приведем фрагменты кода, демонстрирующие использование синтаксиса декоратора в Tablib, а также задействуем класс property (https://docs.python.org/library/functions.html#property) для создания унаследованных атрибутов вроде ширины и высоты набора данных. Помимо этого, покажем, как динамически он регистрирует форматы файлов, чтобы избежать дупликации шаблонного кода для разных типов формата (CSV, YAML и т. д.).

В последних двух подразделах мы рассмотрим, как Tablib использует зависимости, полученные от третьей стороны, а затем обсудим свойство __slots__ объектов нового класса. Вы можете пропустить эти разделы и при этом продолжать жить счастливой питонской жизнью.