Sphinx: документирование кода в Python Python 15.09.2010

Предыстория

С именем sphinx в мире питона связан один парадокс, само это имя настолько припало по душе разработчикам, что существует целых три (известных мне) проекта которые именуются sphinx :).

В этой небольшой заметке я опишу использование Sphinx, который Python documentation generator. Полезность документации прямо пропорциональна времени существования проекта, т.е. чем дольше живет проект, тем желательнее наличие хорошей документации. Это будет полезно как коренным разработчикам - можно освежить в памяти подзабытые моменты, так и новым трудовым вливаниям.

Sphinx - инструмент для трансляции файлов с разметкой reStructuredText (reST) в готовую документацию, в любом из поддерживаемых форматов (html, pdf, etc.), поддерживается автоматическая расстановка перекрёстных ссылок, индексов, сносок, подсвечивание синтаксиса кода, отображение формул, построение графиков и т.д. Изначально sphinx разрабатывался для документирования языка python, но со временем добавились и другие языки (C++, JavaScript).

Коротко о возможностях sphinx:

• на выходе можно получить любой из поддерживаемых форматов: html, pdf, plain text, etc.
• богатые возможности по построению перекрестных ссылок между страницами, классами, функциями и т.д.
• построение иерархической структуры документации, с ссылками на разные уровни
• подсветка кода, используется Pygments
• набор расширений, например для тестирования кода в docstrings

Для разметки используется reStructuredText. Огромный список проектов использующих sphinx.

Установка и создание первой документации

Установим sphinx через pip

pip install Sphinx

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

mkdir ~/temp/sdoc/
cd ~/temp/sdoc/
sphinx-quickstart 

Ответы на большинство задаваемых вопросов можно оставить по-умолчанию, но некоторые стоит подправить. Ответ на вопрос про имя проекта и версию вводите по своему желанию.

Разделяем папки с исходным материалом и уже собранной в кучу документацией

> Separate source and build directories (y/N) [n]: y

Включение расширения autodoc, оно нам понадобится для выдирания docstring из исходников, отвечаем y

> autodoc: automatically insert docstrings from modules (y/N) [n]: y

Я запускаю sphinx под ubuntu, потому мне не нужен bat'ник

> Create Windows command file? (Y/n) [y]: n

В корне создаваемой документации обычно присутствует две директории и один файл:

• build - в этой директории хранится собранная в кучу документация;
• source - тут лежат исходные файлы с разметкой reST, шаблоны, статика и конфигурационный файл conf.py;
• файл Makefile - скрипт, в котором удобно собраны параметры для построителя документации sphinx-build

В папке source также находится мастер файл (index.rst), который является главным файлом документации и в котором находится содержание документации.

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

Создадим простую документацию используя базовый набор из reST разметки. В директории-источнике (source) создадим файл test.rst, с ниже приведенным содержанием, в source/_static положим файл с изображением python.png.

*********************
CHAPTER 1 Hello world
*********************

Форматирование текста
=====================

| *— Извините, я опоздал.*
| *— Что случилось?*
| *— Да ничего, я просто не хотел приходить.*
| **Теория большого взрыва**

* Шелдон Купер
* Пенни
* Леонард Хофстэдер
* и т.д.

#. Сезон 1
#. Сезон 2

.. note::
    Ждите новые сезонны в сентябре.

Последние `новости `_ о сериале.

Форматирование кода
===================

Логотип python:

.. image:: _static/python.png


Куски исходного кода вставляются так::

   for i in xrange(1,5):
         print i

или так 

>>> for i in xrange(1,5):
...    print i

Теперь добавим созданный документ в оглавление, для этого подправим файл index.rst

Welcome to sphinx test's documentation!
=======================================

Contents:

.. toctree::
   :maxdepth: 2

   test.rst

Indices and tables
==================

* :ref:`genindex`
* :ref:`modindex`
* :ref:`search`

Соберем тестовую документацию в html-вариант:

make html

У меня получилась такая странница

Contents:

.. toctree::
   :maxdepth: 2

   test.rst

   films.rst

*******************************************
CHAPTER 2 Модуль films из проекта на Django 
*******************************************

Модель
======

.. automodule:: films.models
    :members:   

Вид
======

.. automodule:: films.views
    :members:   

export PYTHONPATH=~/temp/cinema/

from django.conf import settings
settings.configure()

html_theme = "natura"