Создай, оформи, опубликуй. Sphinx — незаменимый помощник в мире Python документации

Привет, Хабр!

Меня зовут Рожнев Андрей, участник профессионального сообщества NTA.

В данной статье пройдём путь от знакомства с мощным инструментом для документации Sphinx до публикации нашей собственной документации на GitHub Pages. Мы узнаем насколько широко Sphinx используется в мире открытого исходного кода, включая такие проекты как Django, The Linux Kernel, TensorFlow, Pandas и многие другие.

Быстрая навигация по посту

• Что такое Sphinx?

• Инициализация Sphinx

• Интеграция Sphinx c Django

• Автоматическая генерация документации

• Генерация документации в форматах HTML и PDF

• Основы работы с reStructuredText

• Публикация документации

• Заключение

Что такое Sphinx?

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

Sphinx использует простой в разметке текстовый формат reStructuredText (reST) для создания документации, и способен компилировать эту разметку в различные форматы, такие как HTML, PDF, ePub, Texinfo, и другие.

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

Где используется Sphinx?

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

• Python Documentation
  Как уже было сказано выше, Sphinx первоначально был создан для документирования самого языка Python, и по‑прежнему используется на официальном сайте Python для предоставления документации по языку и стандартным библиотекам.

• Read the Docs
  Это популярная платформа для хостинга документации, которая тесно интегрирована с Sphinx. Она позволяет автоматически собирать и публиковать документацию из репозиториев на GitHub, GitLab и других сервисах. Read the Docs поддерживает формат reStructuredText и предоставляет множество дополнительных функций для улучшения качества документации.

Проекты с открытым исходным кодом, корпоративные и научные проекты.

Множество проектов с открытым исходным кодом используют Sphinx для создания их документации. Некоторые из них включают:

• Django
  Это высокоуровневый веб‑фреймворк Python, который следует принципу «Не изобретай велосипед». Документация Django, известная своим высоким качеством и полнотой, написана с использованием Sphinx. Это включает подробные справочные материалы, руководства по разработке, и руководства по API. Использование Sphinx в таком масштабном и влиятельном проекте, как Django, является отличным подтверждением его надежности и эффективности.

• The Linux Kernel
  Sphinx используется для документирования ядра Linux, одного из самых значимых и сложных проектов с открытым исходным кодом в мире.

• TensorFlow
  Платформа от Google для машинного обучения. Документация TensorFlow, которая включает в себя описания API, руководства и учебные материалы, создана с использованием Sphinx.

• Pandas
  Библиотека Python для обработки и анализа данных, которая использует Sphinx для создания своей обширной документации, включающей справочные материалы, руководства и учебные пособия.

• NumPy
  Библиотека для научных вычислений на Python, которая широко использует Sphinx для создания своей документации. Это подтверждает статус Sphinx как стандартного инструмента для документации в научной и академической среде Python.

Инициализация Sphinx в нашем проекте

Где скачать Sphinx?

Sphinx — это программное обеспечение с открытым исходным кодом, и его можно легко установить с помощью пакетного менеджера Python — pip. Для установки Sphinx, выполним следующую команду в терминале:

$ pip install Sphinx

Также можно посетить официальный сайт Sphinx для получения дополнительной информации.

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

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

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

 $ mkdir docs

Инициализация Sphinx

Перейдём в созданную директорию и запустим Sphinx‑Quickstart — это утилита, которая инициализирует Sphinx в нашем проекте. Данная утилита стала доступна после установки Sphinx посредством pip.

$ cd docs

$ sphinx-quickstart

Эта команда запустит интерактивный процесс, который задаст некоторые вопросы о нашем проекте и о том, как мы хотим настроить Sphinx.

Например, он спросит, хотим ли мы использовать автогенерацию документации API, включить тестирование doctest, название проекта, авторство, версию проекта и многое другое.

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

После того, как мы ответим на все вопросы, Sphinx‑Quickstart создаст несколько файлов и директорий в docs, включая conf.py, который содержит основную конфигурацию Sphinx, а также index.rst, который является главной страницей документации.

Пример сгенерированного conf.py

Получившаяся иерархия файлов и папок после выполнения команды:

 $ sphinx-quickstart

Интеграция Sphinx с Django. Эффективное создание документации с использованием sphinxcontrib_django

Рассмотрим возможность подключения сторонних расширений для Sphinx на примере Django. В этом разделе мы посмотрим, как интегрировать Sphinx с Django и как использовать расширение sphinxcontrib_django для улучшения этого процесса.

Подключение Sphinx к Django-проекту

Для начала, нам необходимо сказать Sphinx где находятся настройки и корневая директория Django. Мы можем сделать это добавив следующий код в файл conf.py, который был сгенерирован Sphinx в директории docs:

import os
import sys

# Указываем путь до root-папки проекта Django
# Путь относительно файла conf.py 
sys.path.insert(0, os.path.abspath('../'))


django_settings = 'Sphinx.settings'

Указанный выше Sphinx.settings — это путь к файлу настроек нашего Django‑проекта. Это позволит Sphinx обращаться к моделям и другим компонентам Django‑проекта при генерации документации.

Использование расширения sphinxcontrib_django

Теперь давайте поговорим о расширении sphinxcontrib_django. Это стороннее расширение предоставляет возможности для более глубокой интеграции Sphinx с Django.

Но почему мы должны использовать это расширение? Оно позволяет автоматически генерировать документацию для моделей Django и предоставляет специальные директивы для взаимодействия с Django‑кодом. Это делает процесс документирования более эффективным и позволяет избежать дублирования кода.

Для установки расширения используем pip:

$ pip install sphinxcontrib‑django

Теперь нам необходимо активировать расширение, добавив его в список расширений в файле conf.py:

extensions = [
    # другие расширения, если есть
    'sphinxcontrib_django',
]

С этого момента мы можем использовать специальные директивы и возможности, предоставляемые sphinxcontrib_django, такие как автоматическую генерацию документации для моделей.

Автоматическая генерация документации из docstrings. Сфокусируйтесь на коде, Sphinx сделает остальное

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

Подключение автоматической генерации документации

Sphinx предоставляет расширение autodoc, которое позволяет нам автоматически генерировать документацию из docstrings. Чтобы использовать это расширение нам необходимо добавить 'sphinx.ext.autodoc' в список расширений в файле conf.py:

extensions = [
    'sphinxcontrib_django',
    'sphinx.ext.autodoc',
]

Использование docstrings в коде

Теперь, когда autodoc активирован, давайте убедимся, что наш код содержит docstrings. В качестве примера, давайте попробуем сделать документацию «игрушечного» представления (View) фреймворка Django.

Содержимое модуля views.py приложения test_app:

Код

from django.contrib.auth.mixins import LoginRequiredMixin, UserPassesTestMixin
from django.shortcuts import redirect
from django.urls import reverse_lazy
from django.views.generic import UpdateView

from .forms import PostForm
from .models import Post


class PostUpdateView(LoginRequiredMixin, UserPassesTestMixin, UpdateView):
    """
    View for updating a Post instance. Only the author of the        post or an
    authenticated user with the right permissions can update the post.

    :ivar model: The model to be used by the view, in this case, Post.
    :vartype model: Model
    :ivar form_class: The form class to be used for updating the Post instance.
    :vartype form_class: ModelForm
    :ivar template_name: The path to the HTML template to be used for rendering the view.
    :vartype template_name: str
    :ivar pk_url_kwarg: The name of the URL keyword argument that contains the primary key
                       of the object that is to be updated.
    :vartype pk_url_kwarg: str
    """

    model = Post
    form_class = PostForm
    template_name = 'posts/post_update.html'
    pk_url_kwarg = 'post_id'

    def test_func(self):
        """
        Checks if the user requesting the update is the author of the post.

        :return: True if the user is the author of the post, False otherwise.
        :rtype: bool
        """
        post = self.get_object()
        return post.author == self.request.user

    def handle_no_permission(self):
        """
        Handles the scenario where the user does not have permission to update the post.
        It redirects the user to the post detail view.

        :return: A redirect response to the post detail view.
        :rtype: HttpResponseRedirect
        """
        post_id = self.kwargs['post_id']
        return redirect('posts:post_detail', post_id=post_id)

    def get_success_url(self):
        """
        Specifies the URL to redirect to when the form is successfully validated and the object is saved.

        :return: A string representation of the URL to redirect to the user's profile page.
        :rtype: str
        """
        return reverse_lazy('posts:user_profile', kwargs={'username': self.request.user})

Включение docstrings в документацию

Теперь, когда у нас есть код с docstrings, давайте включим его в нашу документацию. Для этого создадим файл views.rst (прямо в директории docs) и добавим в него следующее:

Views
=====

.. automodule:: test_app.views
   :members:
   :undoc-members:

В конкретном случае, строки c automodule, members и undoc‑members являются директивами для Sphinx, которые позволяют автоматически генерировать документацию на основе исходного кода Python.

Вот что означают эти директивы:

• .. automodule:: test_app.views
  Эта директива указывает, что должен быть сгенерирован автоматический раздел документации для модуля test_app.views. Sphinx найдет этот модуль и извлечет информацию о его содержимом для документации.

• :members:
  Эта директива указывает Sphinx включить все члены модуля в сгенерированную документацию. Члены модуля включают функции, классы, переменные и другие атрибуты, определенные в модуле test_app.views.

• :undoc‑members:
  Эта директива указывает Sphinx включить в документацию также те члены модуля, для которых отсутствует документация. То есть, даже если некоторые члены модуля test_app.views не были явно задокументированы, они все равно будут включены в сгенерированную документацию.

После чего в index.rst следует добавить следующее:

Документация myproject
======================

.. toctree::
   :maxdepth: 2
   :caption: Пример документации views

   ./views.rst

• .. toctree::
  Эта директива Sphinx используется для создания древовидной структуры (содержания) для документации. Она указывает, что должно быть создано содержание, которое будет включать другие файлы документации.

• :maxdepth: 2 
  Этот параметр директивы toctree указывает на максимальную глубину вложенности содержания. В данном случае 2 означает, что содержание будет содержать текущий уровень и один уровень вложенности, то есть файлы, указанные в toctree, и файлы, которые они включают.

• :caption:
  Пример документации views: Этот параметр директивы toctree определяет заголовок, который будет отображаться для этого раздела содержания. В данном случае заголовок будет «Пример документации views».

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

Генерация документации в форматах HTML и PDF

После того, как мы настроили Sphinx, написали docstrings и подготовили содержание документации, приходит время выбрать форматы, в которых мы хотим предоставить нашу документацию пользователям. В этом разделе мы рассмотрим, как сгенерировать документацию в форматах HTML и PDF.

Генерация HTML-документации

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

Для начала убедимся, что мы находимся в директории, где хранится наша документация (в папке docs). Теперь, для создания HTML‑версии нашей документации, выполним следующую команду:

$ make html

После выполнения этой команды Sphinx сгенерирует HTML‑файлы и поместит их в поддиректорию _build/html. Мы можем открыть файл index.html в веб‑браузере и увидеть результат:

Генерация PDF-документации

Иногда нам требуется предоставить документацию в виде статического PDF‑файла, который можно распечатать или сохранить для оффлайн‑использования. Sphinx использует LaTeX (библиотека Python для работы с разметкой текста) для генерации PDF‑документов, поэтому перед тем, как продолжить, убедимся, что у нас установлены необходимые LaTeX‑пакеты. На примере Ubuntu это можно сделать с помощью команды:

# apt‑get install texlive‑latex‑recommended texlive‑fonts‑recommended texlive‑latex‑extra latexmk

Теперь, когда у нас есть все необходимые зависимости, давайте сгенерируем PDF‑версию нашей документации. В директории документации выполним следующую команду:

$ make latexpdf

Это создаст PDF‑файл в поддиректории _build/latex.

Основы работы с reStructuredText. Создание мощной документации с лёгкостью

Когда мы говорим о создании документации с помощью Sphinx, одной из ключевых тем, которую нельзя обойти, является reStructuredText (reST). Это текстовый формат разметки, который используется Sphinx для организации и структурирования нашего контента. В этом разделе мы погрузимся в основы работы с reStructuredText.

Что такое reStructuredText? Это гибкий и мощный язык разметки, который позволяет нам добавлять структуру и форматирование в текстовые документы. В отличие от Markdown (ещё один из самых популярных и простых языков разметки), reST обладает большей сложностью и гибкостью, что делает его идеальным для написания технической документации.

Заголовки и секции

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

Пример:

Глава первая
============

Секция 1
--------

Подсекция 1.1
~~~~~~~~~~~~~

Списки и перечисления

Списки — это еще один важный элемент документации. В reST мы можем создать ненумерованные и нумерованные списки с легкостью:

- Первый маркированный элемент
- Второй маркированный элемент

1. Первый пронумерованный элемент
2. Второй пронумерованный элемент

Или

#. Первый пронумерованный элемент
#. Второй пронумерованный элемент

Гиперссылки

Ссылки неотъемлемы для хорошей документации. В reST, ссылки можно создать, используя следующий синтаксис:

Ссылка на Django Coding Style <https://docs.djangoproject.com/en/dev/internals/contributing/writing‑code/coding‑style/>`_

Изображения

Добавление изображений также просто. Мы можем вставить изображение, используя директиву image:

.. image:: путь/к/изображению.png
   :alt: Альтернативный текст

Работа с кодом

Для вставки примеров кода мы используем директиву code. Мы также можем указать язык программирования для синтаксической подсветки:

.. code:: python

   def function():
       print("Пример кода")

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

Публикация документации на GitHub Pages

Создание превосходной документации — это только половина битвы. Теперь, когда у нас есть полноценная документация, созданная с помощью Sphinx, нам нужно опубликовать её, чтобы другие люди могли иметь доступ к этой ценной информации. В этом разделе мы рассмотрим, как опубликовать нашу документацию на GitHub Pages.

Что такое GitHub Pages?

GitHub Pages — это сервис хостинга от GitHub, который позволяет нам публиковать статические веб‑сайты и документацию прямо из репозитория на GitHub. Это прекрасное решение для публикации документации, поскольку оно бесплатно и интегрируется непосредственно с нашими репозиториями на GitHub.

Настройка GitHub Pages

Теперь перейдем к настройке GitHub Pages. Для этого перейдем в наш репозиторий на GitHub и откроем вкладку Settings. Пролистаем вниз до раздела GitHub Pages.

Выберем ветку, которую хотим использовать для GitHub Pages. Обычно для этого используют ветку main или gh‑pages (последнюю ветку нужно предварительно создать). Также укажем папку, в которой находятся сгенерированные HTML‑файлы (в нашем случае — docs).

Загрузка документации на GitHub

После настройки GitHub Pages загрузим нашу сгенерированную документацию в репозиторий. Мы можем сделать это, добавив файлы в репозиторий и сделав commit и push.

$ git add _build/html
$ git commit -m "Add Sphinx documentation"
$ git push origin gh-pages

Проверка нашего сайта с документацией

После того, как мы загрузили документацию, GitHub Pages автоматически обработает наши файлы и опубликует веб‑сайт. Мы можем перейти по предоставленной ссылке (https://<username>.github.io/<repository>) и увидеть нашу документацию во всей красе!

GitHub
Pages представляет собой простое и эффективное решение для публикации
документации. Благодаря тесной интеграции с GitHub мы можем легко обновлять и управлять нашей документацией, делая её доступной для широкой аудитории. Это идеальный способ поделиться нашими знаниями и результатами работы с сообществом.

Заключение

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

Особое внимание было уделено автоматической генерации документации из docstrings, что позволяет нам эффективно извлекать информацию прямо из исходного кода. Это не только упрощает процесс создания документации, но и обеспечивает её актуальность.

Далее мы погрузились в мир reStructuredText, текстового формата разметки, который является основой Sphinx. Мы узнали, как создавать заголовки, списки, вставлять изображения и форматировать код.

Когда наша документация была готова, было сказано, как сгенерировать её в различных форматах, таких как HTML и PDF, чтобы сделать её доступной для различных аудиторий.

Наконец мы завершили наше путешествие изучив как опубликовать документацию на GitHub Pages. Этот шаг позволил нам поделиться нашей работой с миром и сделать её доступной для всех заинтересованных сторон.

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