time

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

sphinx_doc.png

Предыстория

С именем 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

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

Документирование кода для проекта на Django

Для начала в мастер-файл index.rst добавим упоминание файле в котором будет содержатся описание тестовой модели Film и вида для этой модели. Для этого в директиве .. toctree::, отвечающей за оглавление, добавим films.rst после test.rst:

Contents:

.. toctree::
   :maxdepth: 2

   test.rst

   films.rst

Содержимое файла films.rst

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

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

.. automodule:: films.models
    :members:   

Вид
======

.. automodule:: films.views
    :members:   

Тестовые образцы файлов models.py и views.py.

Теперь поможем sphinx найти наш модуль, для этого в PYTHONPATH добавим путь к этому модулю, у меня это выглядит так

export PYTHONPATH=~/temp/cinema/

еще sphinx должен увидеть django-среду, для этого в conf.py, в начало, добавим

from django.conf import settings
settings.configure()

Собираем все это в кучу и любуемся результатом:

Оформление документации

В поставке с sphinx идет набор разных оформлений, которые можно переключать всего одной правкой в conf.py, например

html_theme = "natura"

После этого надо заново скомпилировать документацию - make html.

Макофилы должны заценить тему ADCtheme.

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

Дополнительное чтиво

blog comments powered by Disqus