Модуль PythonDoc: генератор документации для Python-программ. Первые впечатления

Корольков Дмитрий

3 ноября 2003 года вышел финальный релиз PythonDoc 2.0 — программы для генерации описания питоновских программ по их исходному тексту. Программа, написанная, конечно же, на Python, разбирает исходный текст и извлекает информацию из специальным образом составленных комментариев. По назначению и синтаксису комментариев программа практически аналогична JavaDoc, Doxygen и другим подобным инструментам.

Выходные форматы: HTML и XML.

Описание на английском языке на сайте автора.

Запуск программы

Для создания документации для вашей программы нужно ввести в командной строке:

pythondoc.py [опции] ваша_программа.py

pythondoc.py [опции] каталог

В первом случае pythondoc обработает указанный файл, во втором — все файлы в указанном каталоге.

pythondoc позволяет задавать следующие опции:

• -pпрефикс Задаёт префикс имени файла. Без этой опции имя результирующего файла выглядит как pythondoc-ваша_программа.расширение. Если префикс задан, то имя будет таким: pythondoc-префикс.ваша_программа.расширение. Расширения файлов: html и xml для HTML и XML форматов соответственно.
• -f Заставляет pythondoc создать документацию для файлов, не содержащих специальных pythondoc-комментарием. По умолчанию документация для таких файлов не создаётся.
• -x Заставляет pythondoc создать документацию в формате XML. По умолчанию она создаётся только в HTML-формате. При указании данной опции документация создаётся в обоих форматах.
• -Oформат Позволяет задавать собственный выходной формат. В данной статье эта возможность не рассматривается.
• -Dимя[=значение] Позволяет задавать переменные с указанием или без указания значения, для передачи собственному генератору выходного формата (опция -O)

Кодировка исходного текста

pythondoc понимает стандартное для питоновских исходников указание кодировки в первой или второй строке файла. Например:

#!/usr/bin/python
# -*- coding: KOI8-R -*-

# -*- coding: CP1251 -*-

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

Строки комментария должны располагаться перед описываемым объектом кода, и иметь тот же отступ. Комментарий начинается со строки, содержащей два символа "#". Далее следуют строки, начинающиеся с одиночного символа "#" (после соответствующего отступа) и содержащие текст комментария.

##
# Описание класса
class my_base_class:
  ##
  # Описание метода
  def hello(self):
    print "Hello!"

Отдельные смысловые части текста отмечаются тегами. Список тегов:

• @param параметр функции. Первое слово после тега — имя параметра, всё остальное — его описание.
• @keyparam подобен @param, применяется для описания необязательных параметров.
• @return значение, возвращаемое функцией.
• @exception исключение, которое может генерировать функция. Первое слово после тега — имя исключения, затем идёт описание.
• @throws аналог @exception, введён для совместимости с JavaDoc.
• @def позволяет указать pythondoc как описывать функцию или метод. По умолчанию (при отсутствии данного тега) анализируется текст определения функции и из него извлекаются имена параметров. При использовании @def необходимо задать как имя функции, так и список аргументов.
• @defreturn (экспериментальный). Позволяет указать более краткое описание возвращаемого значения.
• @see введён для создания перекрёстной ссылки. Не используется стандартным генератором.

Описание модуля

Описание начинается и заканчивается строками, содержащими два символа "#". Между ними располагаются строки с текстом комментария, начинающиеся с одиночного символа "#".

##
# Описание модуля
##

Описание класса

Комментарий помещается перед определением класса. При описании обычно применяются теги @param, описывающие параметры метода __init__.

##
# Класс сцепляет строки используя указанный или заданный по
# умолчанию разделитель.
#
# @param separator разделитель строк.
class my_class(my_base_class):
	"""Сцепление двух строк

	Создание экземпляра:
	obj = my_class(разделитель_по_умолчанию)
	Обращение:
	obj(строка1, строка2[, разделитель]) -> результат_сцепления_строк
	"""
	##
	# Инициализация. Указываем разделитель.
	# @param separator разделитель
	def __init__(self, separator):
		self.separator = separator

	##
	# Сцепляет строки.
	# @param a первая строка
	# @param b вторая строка
	# @keyparam separator разделитель
	# @return строки, сцепленные с использование разделителя.
	def __call__(self, a, b, separator=None):
		if separator:
			return a + separator + b
		else
			return a + self.separator + b
	

Описание функции(метода)

При описании функции могут применяться все задействованные на данный момент теги. Кроме общего описания функции (текст перед всеми тегами) описываются параметры (теги @param и @keyparam), возвращаемое значение (тег @return) и генерируемые функцией исключения (тег @exception или @throws). Для краткого описания могут применяться теги @def и @defreturn. При описании метода параметр self не описывается.

##
# Функция для непонятно каких действий.
#
# @param param1 первый параметр
# @param param2 второй параметр
# @keyparam param3 необязательный параметр
# @return некое число
# @exception ZeroDivisionError
# @def func(p1,p2[,p3]) -> number
# @defreturn результат
def func(param1, param2, param3=0):
  return param1/param2+param3

##
# Просто переменная.
var1 = 1

Ошибки

pythondoc игнорирует первый атрибут класса, если у класса отсутствует строка документации. Как мне кажется, это не слишком мешает использованию программы, так как желательно, чтобы строка документации присутствовала в каждом классе. Однако, разработчики знают об этой ошибке, исправление уже готово и, видимо, войдёт в следующую версию. Автор программы прислал мне патч для версии 2.1a1, исправляющий эту ошибку. На свой вопрос, могу ли я разместить патч на своём сайте, ответа я не получил, поэтому решил его разместить. Если потребуют убрать — уберу. Патч:

@@ -500,9 +501,8 @@
             # method/function/class definition
             definition = self.subject[0] in ("def", "class")
             if definition:
-                if type != tokenize.INDENT:
-                    if (type != tokenize.COMMENT and
-                        type not in WHITESPACE_TOKEN):
+                if type != tokenize.INDENT and type != tokenize.COMMENT:
+                    if type not in WHITESPACE_TOKEN:
                         self.subject.append(token)
                     return self.process_subject # keep going
                 if self.subject[-1] == ":":
@@ -604,9 +604,9 @@
             subject_info.insert(0, elem)
 
         if definition:
-            return self.skip_subject_body
+            return self.skip_subject_body(type, token, start, end, line)
         else:
-            return self.look_for_pythondoc
+            return self.look_for_pythondoc(type, token, start, end, line)
 
     ##
     # Processes a PythonDoc comment.  This method creates an "info"

Заключение

pythondoc.py pythondoc.py