Пошаговое руководство по автодокументированию вашего кода Python

Хотя тщательная документация необходима, ее часто откладывают на задний план и рассматривают как рутинную и низкоприоритетную задачу. Как разработчику легко вернуться к мысли «зачем документировать код, если вы, автор, точно знаете, что он делает?» Когда код быстро меняется, поддержание документации в актуальном состоянии становится еще более серьезным бременем.

К счастью, ручное написание документации не требуется из-за возможностей Sphinx, инструмента, который автоматически генерирует документацию из строк документации в вашем коде.

Ниже приведено пошаговое руководство по автоматическому созданию чистой и хорошо организованной документации из кода Python с использованием Sphinx.

1. Установите Sphinx

Sphinx можно установить с помощью pip, открыв терминал и запустив pip install -U Sphinx, или загрузив официальный пакет Python.

Здесь - официальная страница с описанием других способов установки Sphinx в зависимости от вашей платформы.

2. Инициализируйте конфигурацию Sphinx.

В корневом каталоге вашего проекта запустите sphinx-quickstart, чтобы инициализировать исходный каталог sphinx для создания конфигурации по умолчанию. При запуске этой команды вам будет предложено указать некоторые базовые свойства конфигурации, такие как создание отдельных каталогов исходного кода и сборки, имя проекта, имя автора и версия проекта.

Как показано выше, выполнение команды sphinx-build создает файл Makefile, make.bat, а также каталоги build и source.

3. Обновите файл conf.py

Файл conf.py внутри папки source описывает конфигурацию Sphinx, которая управляет тем, как Sphinx создает документацию. Если вы хотите переопределить тему, версию или каталог модуля, вам нужно будет переопределить эти изменения здесь. Ниже приведены некоторые рекомендуемые переопределения:

Обновите тему

Тема по умолчанию для сфинкса - алебастр. Есть много существующих тем на выбор, и вы даже можете создать свою собственную. Рекомендуемая тема - sphinx_rtd_theme, это красивая, современная, удобная для мобильных устройств тема.

Чтобы использовать sphinx_rtd_theme, вам необходимо установить пакет Python sphinx-rtd-theme, запустив pip install sphinx-rtd-theme в терминале или загрузив тему здесь.

Обновите переменную html_theme внутри файла conf.py, чтобы она указывала на желаемое имя темы:

Обновите версию

Во время каждого выпуска вы хотите обновлять версию документации, чтобы указать на версию выпуска проекта, вручную или с помощью автоматизированного процесса.

Укажите расположение модулей Python

Обновите системный путь, чтобы он указывал на каталог модулей проекта, чтобы sphinx мог найти исходные файлы. Строки 13–15 добавляют каталог модуля к системному пути и по умолчанию закомментированы. Раскомментируйте эти строки и обновите строку, которая читает sys.path.insert(0, os.path.abspath(‘.’)), чтобы добавить каталог, содержащий модули Python.

Добавить поддержку расширений для autodoc

Переменная extensions назначается списку расширений, необходимых для создания документации. Например, если вы планируете включить документацию из своего документа с помощью директив autodoc, вам необходимо активировать ее, добавив sphinx.ext.autodoc в список расширений.

Добавить поддержку расширений для строк документов в стиле NumPy и Google Doc

Это, конечно, необязательно в зависимости от предпочтительного формата строки документации. Если документация в вашем коде соответствует Руководству по стилю Google Python, вам нужно добавить sphinx.ext.napoleon в список расширений.

4. Автоматически сгенерируйте первые файлы.

Sphinx генерирует HTML-документацию из файлов reStructuredText (rst). Эти первые файлы описывают каждую веб-страницу и могут содержать директивы autodoc, которые в конечном итоге автоматически генерируют документацию из строк документации. Эти файлы создаются автоматически, поэтому нет необходимости вручную записывать директивы autodoc для каждого класса и модуля.

Команда sphinx-autodoc автоматически сгенерирует первые файлы с директивами autodoc из вашего кода. Эту команду нужно запускать только при добавлении нового модуля в проект.

Во-первых, убедитесь, что расширение sphinx.ext.autodoc включено в список расширений в conf.py, как описано в разделе выше.

Чтобы автоматически сгенерировать первые файлы, запустите команду sphinx-apidoc, используя следующий синтаксис:

sphinx-apidoc -o <OUTPUT_PATH> <MODULE_PATH>

В нашем примере выходной каталог - source, а каталог модуля - python.

sphinx-apidoc -f -o source python

Выполнение sphinx-apidoc -o source python команды сгенерирует первые файлы test.rst и modules.rst. test.rst включает директивы для написания документации для классов и функций в test.py, а modules.rst содержит список файлов модулей, которые нужно включить на страницу модулей (т. Е. Тестировать).

5. Создайте HTML

Теперь, когда у вас настроены конфигурация и первые файлы, мы можем запустить команду make html из терминала в главном каталоге, чтобы сгенерировать файлы HTML. Файлы HTML будут созданы внутри папки build / HTML.

Как вы можете видеть в этом конкретном случае, предупреждение Warning: "Document isn't included in any toctree было выдано, поскольку мы не включили файл modules.rst ни в одно дерево токтридов. Чтобы исправить это, добавьте modules под директивой toctree в index.rst, как показано ниже:

Снова запускаем сборку:

Файлы HTML были созданы в папке build / HTML. Откройте index.html в браузере, чтобы просмотреть сгенерированные документы:

6. Расширенная разметка Sphinx

Существуют дополнительные директивы Sphinx, которые помогут вашей документации выглядеть более современной и организованной. Вот некоторые из основных полезных функций, которые помогут вам в дальнейшей настройке документации. Все примеры созданы с помощью sphinx_rtd_theme:

Содержание

Sphinx использует специальную директиву, известную как директива toctree, для описания отношений между различными файлами в виде дерева или оглавления.

Ящик для заметок

Поле для заметок можно создать с помощью директивы note.

.. note:: This is a **note** box.

Предупреждающее окно

Окно предупреждения можно создать с помощью директивы warning.

.. warning:: This is a **warning** box.

Изображение

Изображение можно добавить с помощью директивы image.

Стол

Таблицу можно добавить с помощью директивы table.

Ресурсы

Заключение

В этой статье мы рассмотрели основы, необходимые для настройки и сборки документации Sphinx для любого проекта Python. Sphinx полагается на первые файлы, поэтому возможна любая настройка, которую может обрабатывать reStructuredText. Мы надеемся, что знание возможностей Sphinx и средств автоматизации для создания документации побудит вас писать и поддерживать документацию в актуальном состоянии.