Простое и удобное создание документации в Sphinx

Создание эффективных и удобочитаемых документов

Узнайте, как с помощью инструмента Sphinx создавать удобные в сопровождении основанные на стилях документы, которые можно сохранять в различных форматах (например, в HTML).

Альфредо Деза, программист, Независимый разработчик

фотография Альфредо ДезаАльфредо Деза (Alfredo Deza) – опытный программист и системный администратор, в прошлом – профессиональный спортсмен, участник Олимпийских игр. Является активным сторонником свободного ПО, регулярно выступает с докладами на международных конференциях, таких как PyCon. В свободное время занимается фотографией и участвует в различных Open source-проектах.



27.06.2013

Введение

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

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

Подсвечивание текста

По умолчанию текст подсвечивается в Sphinx так же, как и в Python, но можно настроить цветовое выделение так, как в других языках программирования, например, в C или Ruby.

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

Требования

Для работы в Sphinx в основном используется интерфейс командной строки, поэтому использование терминала (консоли) Linux® или UNIX® не вызовет у вас каких-либо неудобств.

В системе должен быть установлен Python. Во всех основных дистрибутивах Linux и некоторых UNIX-подобных операционных системах (например, Mac OSX) Python уже установлен и готов к использованию. Sphinx работает с версиями Python 2.4, 2.5 и 2.6. Чтобы проверить, какая версия Python установлена в вашей системе, выполните команду из листинга 1.

Листинг 1. Проверка версии Python
$ python --version
Python 2.6.1

Синтаксис

Для управления документами Sphinx использует синтаксис разметки текста reStructuredText (с некоторыми дополнениями). Если вы когда-нибудь работали с обычными текстовыми файлами, то, возможно, достаточно знакомы с синтаксисом, который хорошо подойдет для работы в Sphinx.

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

Листинг 2. Пример синтаксиса разметки текста Sphinx
Это заголовок
=============
Заголовок содержит главную тему и отделяется символами '='.
Их количество должно быть не меньше, чем количество символов
в заголовке.

Подзаголовок
------------
Подзаголовки отделяются символами '-'. Их количество должно 
быть тем же, что и количество символов в подзаголовке
(так же, как и в случае с заголовками).

Списки могут быть маркированными:

 * Элемент Foo
 * Элемент Bar

Или же автоматически пронумерованными:

 #. Элемент 1
 #. Элемент 2

Внутренняя разметка
------------––––––-
Слова можно выделять *наклонным* или **полужирным** шрифтами.
Фрагменты кода (например, примеры команд) можно заключать в обратные кавычки, например:
команда ``sudo`` дает вам привилегии суперпользователя!

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

Установка и настройка

Установка выполняется в командной строке и не представляет сложностей (см. листинг 3).

Листинг 3. Установка Sphinx
$ easy_install sphinx
Searching for sphinx
Reading http://pypi.python.org/simple/sphinx/
Reading http://sphinx.pocoo.org/
Best match: Sphinx 1.0.5
Downloading http://pypi.python.org/packages/[...]
Processing Sphinx-1.0.5-py2.5.egg
[...]
Finished processing dependencies for sphinx

Для краткости в листинге 3 приведена лишь часть вывода, но из него видно, что происходит во время инсталляции Sphinx.

Для хранения исходных (в обычном текстовом формате) и конечных (т. е. сгенерированных в том или ином формате) файлов в Sphinx используются различные директории. Например, если мы создаем в Sphinx PDF-файл из исходного текстового файла, то PDF-файл будет сохранен в директорию build. Эту конфигурацию можно изменить, но во избежание путаницы мы будем использовать настройки по умолчанию.

Давайте сразу приступим к созданию нового проекта (см. листинг 4). В процессе вам будет предложено ответить на несколько вопросов. Нажимайте клавишу Enter, чтобы принять все значения по умолчанию.

Листинг 4. Выполнение команды sphinx-quickstart
$ sphinx-quickstart 
Welcome to the Sphinx 1.0.5 quickstart utility.

Please enter values for the following settings (just press Enter to
accept a default value, if one is given in brackets).
[...]

В качестве имени проекта я выбрал имя "My Project"; оно несколько раз будет упоминаться в оставшейся части статьи. Вы можете выбрать любое другое имя.

После выполнения команды sphinx-quickstart в вашей рабочей директории должны появиться файлы, аналогичные файлам в листинге 5.

Листинг 5. Содержимое рабочей директории
.
├── Makefile
├── _build
├── _static
├── conf.py
└── index.rst

Рассмотрим каждый из этих файлов подробнее.

  • Makefile: разработчики, которым приходилось компилировать код, должны быть знакомы с этим файлом. В противном случае просто знайте, что этот файл содержит инструкции для генерации результирующего документа командой make.
  • _build: это директория, в которую будут помещены файлы в определенном формате после того, как будет запущен процесс их генерации.
  • _static: в эту директорию помещаются все файлы, не являющиеся исходным кодом (например, изображения). Позже создаются связи этих файлов с директорией build.
  • conf.py: это файл Python, содержащий конфигурационные параметры Sphinx, включая те, которые были выбраны при запуске sphinx-quickstart в окне терминала.
  • index.rst: это корень проекта. Он соединяет документацию воедино, если она разделена на несколько файлов.

Приступаем к работе

Итак, мы установили Sphinx, посмотрели на структуру проекта по умолчанию и познакомились с основным синтаксисом. Однако не спешите сразу переходить к написанию документов. Не разобравшись со схемой и выходными форматами, вы рискуете запутаться и потерять время при работе над проектом.

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

Сразу же после главного заголовка в файле index.rst находится оглавление. Оно содержит директиву toctree, которая является главным элементом, объединяющим все документы проекта. Если проект содержит дополнительные файлы, которые не перечислены в этой директиве, они не будут включены в состав проекта при его компиляции.

Мы добавим в наш проект новый файл и назовем его example.rst. Этот файл необходимо указать в директиве toctree, однако будьте внимательны. Для правильной работы этого списка необходимо придерживаться определенных правил разметки, а расширение файла указывать не нужно (в нашем случае это расширение .rst). В листинге 6 показано, как должен выглядеть этот список. Имя файла должно быть отделено тремя пробелами от левого поля, а после опции maxdepth должна быть вставлена одна пустая строка.

Листинг 6. Пример директивы toctree в файле index.rst
Contents:

.. toctree::
   :maxdepth: 2

   example

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

Вспомните пример синтаксиса из листинга 2. Скопируйте содержимое этого листинга в файл example.rst и сохраните его. Мы готовы к созданию выходного документа.

Запустите команду make и укажите в качестве конечного формата формат HTML. Сгенерированный вывод можно непосредственно размещать на Web-сайте, поскольку результат будет содержать все необходимое, включая файлы JavaScript и CSS (см. листинг 7).

Листинг 7. Вывод команды make html
$ make html
sphinx-build -b html -d _build/doctrees   . _build/html
Making output directory...
Running Sphinx v1.0.5
loading pickled environment... not yet created
building [html]: targets for 2 source files that are out of date
updating environment: 2 added, 0 changed, 0 removed
reading sources... [100%] index
looking for now-outdated files... none found
pickling environment... done
checking consistency... done
preparing documents... done
writing output... [100%] index 
writing additional files... genindex search
copying static files... done
dumping search index... done
dumping object inventory... done
build succeeded.

Build finished. The HTML pages are in _build/html.

Если вы хотите использовать другие опции команды make, то запустите ее с флагом -h (запрос справочной информации), и вы получите полное описание всех доступных опций (см. листинг 8).

Листинг 8. Просмотр опций команды make
$ make -h
Usage: make [options] [target] ...
Options:
[...]

Переходим к статике

Сгенерировав за один прием HTML-код из двух файлов, мы получили полнофункциональный (статический) Web-сайт.

В директории _build должны появиться две новых директории: doctrees и HTML. Нас интересует директория HTML, содержащая все нужные файлы. Откройте файл index.html в Интернет-браузере, и вы должны увидеть страницу, похожую ту, что изображена на рисунке 1.

Рисунок 1. Главная страница статического HTML
Рисунок 1. Главная страница статического HTML

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

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

Вспомните листинг 6, в котором мы указали отдельный файл с именем example в директиве toctree. Теперь на главной странице видно, что основной заголовок отображается в содержании в виде списка первого уровня, а подзаголовок – в виде списка второго уровня. Sphinx сам позаботился о создании правильной структуры.

Если у вас ничего не получилось с первого раза…

В этом случае внесите необходимые изменения в исходный файл и снова запустите команду make для создания готового проекта.

Все ссылки указывают на нужные места документа, а заголовки и подзаголовки содержат якоря, на которые можно непосредственно ссылаться. Например, раздел Subject Subtitle содержит якорь, который в браузере выглядит как ../example.html#subject-subtitle. Как уже упоминалось, вам не нужно заботиться об этих мелких обыденных вещах.

На рисунке 2 показано, как выглядит файл example.rst в виде статического Web-сайта HTML.

Рисунок 2. Пример страницы в формате HTML
Рисунок 2. Пример страницы в формате HTML

Переходим к графике

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

Синтаксис добавления статических файлов легко запомнить. После того, как вы добавите статические файлы в директорию _static, которая была создана при создании схемы проекта, вы сможете без проблем ссылаться на них. В листинге 9 показано, как должна выглядеть такая ссылка в разметке reStructuredText. В этом примере я размещаю ссылку в самом конце файла example.rst.

Листинг 9. Статический список в файле example.rst
.. image:: _static/system_activity.jpg

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

Рисунок 3. Изображение диаграммы работы системы
Рисунок 3. Изображение диаграммы работы системы

Заключение

В этой статье мы рассмотрели основы работы с Sphinx, но возможности этого инструмента гораздо шире. Sphinx позволяет экспортировать документацию в различные форматы; для этого необходимо устанавливать дополнительные библиотеки и программное обеспечение. Вот лишь некоторые форматы, в которых можно сохранять документацию: PDF, epub, man (man-страницы UNIX) и LaTeX.

Для работы со сложными диаграммами имеется подключаемый модуль, который позволяет добавлять в проекты диаграммы Graphviz. Однажды мне потребовалось создать схему небольшой офисной сети, и с помощью этого инструмента все получилось даже лучше, чем я мог себе представить – я выполнил всю работу, используя единственный инструмент. Помимо Graphviz, существует и множество других подключаемых модулей для Sphinx (также называемых расширениями). Некоторые из них (например, interSphinx, позволяющий связывать несколько отельных проектов) входят в комплект самого Sphinx.

Если созданный вами проект выглядит не совсем так, как вам бы хотелось, то вы можете использовать одну из многочисленных тем Sphinx, полностью изменяющих вид конечных HTML-файлов. Некоторые важные Open Source-проекты (например, Celery и Lettuce) позволяют очень сильно изменять вид HTML путем модификации CSS и расширения шаблонов. В разделе Ресурсы вы найдете ссылки на эти проекты и на документацию, в которой объясняется, как расширять и модифицировать CSS и схемы по умолчанию.

Sphinx изменил мое представление о создании документации. Я был в полном восторге, когда понял, что могу легко создать документацию для нескольких внутрикорпоративных и своих собственных open source-проектов. Используйте Sphinx, чтобы легко находить забытую информацию в своих собственных документах.


Загрузка

ОписаниеИмяРазмер
Пример кода для этой статьиexample_sphinx_project.zip142 КБ

Ресурсы

Научиться

Обсудить

Комментарии

developerWorks: Войти

Обязательные поля отмечены звездочкой (*).


Нужен IBM ID?
Забыли Ваш IBM ID?


Забыли Ваш пароль?
Изменить пароль

Нажимая Отправить, Вы принимаете Условия использования developerWorks.

 


Профиль создается, когда вы первый раз заходите в developerWorks. Информация в вашем профиле (имя, страна / регион, название компании) отображается для всех пользователей и будет сопровождать любой опубликованный вами контент пока вы специально не укажите скрыть название вашей компании. Вы можете обновить ваш IBM аккаунт в любое время.

Вся введенная информация защищена.

Выберите имя, которое будет отображаться на экране



При первом входе в developerWorks для Вас будет создан профиль и Вам нужно будет выбрать Отображаемое имя. Оно будет выводиться рядом с контентом, опубликованным Вами в developerWorks.

Отображаемое имя должно иметь длину от 3 символов до 31 символа. Ваше Имя в системе должно быть уникальным. В качестве имени по соображениям приватности нельзя использовать контактный e-mail.

Обязательные поля отмечены звездочкой (*).

(Отображаемое имя должно иметь длину от 3 символов до 31 символа.)

Нажимая Отправить, Вы принимаете Условия использования developerWorks.

 


Вся введенная информация защищена.


static.content.url=http://www.ibm.com/developerworks/js/artrating/
SITE_ID=40
Zone=Open source, Linux
ArticleID=935561
ArticleTitle=Простое и удобное создание документации в Sphinx
publish-date=06272013