Как настроить Sphinx для документирования кода Python

Sphinx — один из самых популярных инструментов для создания документации. В сообществе Python разработчики используют это бесплатное программное обеспечение с открытым исходным кодом. Он может извлекать текст непосредственно из вашего кода или файлов уценки, а затем использовать его для создания документации в различных форматах, таких как обычный текст, HTML, PDF и EPUB.

Настройка сфинкса

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

Что такое сфинкс и что он делает?

Как уже упоминалось, Sphinx — это генератор документации. По умолчанию он использует язык разметки reStructuredText (RST), но с помощью сторонних расширений он также может используйте Markdown, популярный язык разметки простого текста. Затем он преобразует эти файлы RST или уценки в HTML, PDF, справочные страницы или другие форматы, которые вы предпочитаете.

Некоторые из функций, которые включает Sphinx:

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

Установка Сфинкса

Перед установкой Sphinx убедитесь, что у вас есть Python 3 установлен в вашей среде разработки. Затем вы можете использовать диспетчер пакетов pip для установки Sphinx, выполнив следующую команду в своем терминале:

пип установить сфинкс

Это загрузит и установит Sphinx и его зависимости.

После установки запустите в командной строке следующее.

сфинкс-сборка --версия

Если все работает нормально, вы должны увидеть номер версии только что установленного пакета Sphinx.

Создание нового проекта Sphinx

После того, как вы установили Sphinx, перейдите в свой рабочий каталог и запустите команду sphinx-quickstart, чтобы создать новый проект Sphinx.

сфинкс-быстрый старт

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

Если вы перечислите содержимое своего каталога, вы увидите, что эта команда создает для вас некоторые файлы. conf.py содержит значения конфигурации, а index.rst служит страницей приветствия вашей документации. Каталог сборки будет содержать сгенерированную документацию, и Sphinx использует Makefile (make.bat в Windows) для сборки документации.

Написание документации с использованием Sphinx

Файл index.rst в корне вашего каталога является домашней страницей вашего приложения. Итак, откройте его в текстовом редакторе, таком как VS Code, или любой другой хороший бесплатный редактор кода— отредактировать.

Вы можете изменить index.rst по своему усмотрению, но одна вещь, которая должна быть, по крайней мере, это корневая директива toctree (дерево оглавления). Это очень важно, так как соединяет несколько файлов в единую иерархию документов.

Чтобы добавить документацию в файл index.rst, вы можете использовать разметку RST.

В качестве примера рассмотрим файл index.rst для модуля math_utils. Этот файл может включать краткий обзор назначения модуля и оглавление со ссылками на другие страницы документации.

Добро пожаловать в математические утилиты
.. toctree::
 :максимальная глубина: 2
Начиная

Для использования этого модуля вам потребуется следующее:
* Питон установлен.
* Текстовый редактор
Математические утилиты

Модуль math-utils предоставляет базовые математические функции, такие как сложение и
вычитание.

При необходимости вы можете добавить дополнительные файлы .rst. Например, вы можете создать руководство по внесению вклада в файл с именем содействие.rst, содержащий следующие указания по внесению вклада.

Руководство по содействию
Мы приветствуем вклад в наш проект! Вот некоторые рекомендации для
вклад:
- Форкнуть проект на GitHub.
- Внесите свои изменения в новую ветку.
- Напишите тесты, чтобы убедиться, что ваши изменения работают правильно.
- Отправьте запрос на вытягивание с вашими изменениями.
- Внесите необходимые изменения.
Спасибо за участие!

Затем вы можете связать этот файл из index.rst, добавив новый раздел в директиву toctree:

.. toctree::
 :максимальная глубина: 2
 :caption: Содержание

 вклад

Это создает новый элемент с именем «вклад» в оглавлении, при нажатии на который пользователь переходит на страницу вклада.

После того, как вы написали документацию, следующим шагом будет ее сборка. Здесь создание документации означает создание страниц HTML, руководств или PDF-файлов из файлов RST.

Создание документации

Чтобы собрать документацию с помощью Sphinx, вам нужно запустить команду make html в корне вашей папки, где находится make-файл.

сделать html

Вы должны увидеть файлы HTML в папке сборки. Если при сборке были ошибки, Sphinx сообщит об этом в терминале.

Чтобы просмотреть документацию, откройте файл index.html в браузере:

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

Настройка документации

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

Чтобы продемонстрировать, попробуйте изменить тему на ту, которая называется природа:

1. Откройте файл конфигурации Sphinx conf.py в каталоге вашего проекта Sphinx.
2. Найдите строку, определяющую параметр html_theme, и измените ее на характер
3. Сохраните файл конфигурации и перестройте документацию, чтобы увидеть ваши изменения.

Вот как должна выглядеть домашняя страница документации.

Если вы не хотите использовать встроенные темы, вы всегда можете использовать сторонняя тема Sphinx вместо.

Документирование кода с помощью строк документации

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

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