Эта статья более подробно рассматривает некоторые нововведения, предложенные Docblox,- системой документирования для PHP 5.3+. Для понимания некоторых вещей необходимо прочитать предыдущую статью. Для простоты в качестве каталога с тестовыми исходными кодами я использовал /src/example/ (/src— симлинк на реальный каталог с моими исходными кодами).
Для работы нам понадобятся некоторые дополнительные библиотеки. Установим их.
Нам понадобится тестовый пример, содержащий для начала уже знакомые нам @-теги PHP Documentor, чтобы понять структуру генерируемого XML-файла, которая на данный момент не документирована на официальном сайте проекта. Возьмем файл Example.php, содержащий класс Example:
Теперь запустим Docblox в каталоге /src/example:
Docblox поддерживает создание различных тем отображения кода. При установке библиотеки при помощи PEAR темы располагаются в каталоге <PEAR_ROOT>/Docblox/data/themes, где <PEAR_ROOT> — место хранения исходных кодов всех установленных пакетов PEAR (например, в Ubuntu <PEAR_ROOT> это /usr/share/php/). Каждая тема располагается в отдельном каталоге и обязательно имеет в своем составе файл template.xml, в котором прописаны правила сборки документации. Файл состоит в основном из строчек вида:
Кроме template.xml любая тема содержит XSL-шаблоны страниц, каскадные таблицы стилей, js-сценарии и т.п. Таким образом, если вы знакомы с XSL-шаблонами, вам не составит труда создать новую тему отображения документации, зная структуру файла structure.xml.
Генерирование документации в формат PDF также не представляет сложностей. Для этого нужно просто использовать стандартную тему pdf в файле конфигурации docblox.xml:
Для генерирования UML-графа необходимо добавить правило в настройки используемой темы (template.xml) следующим образом:
Это позволяет встраивать диаграмму класса в файл с документацией.
Начиная с версии 0.14 Docblox поддерживает @-теги используемые для документирования применения всем известной ORM Doctrine. Добавим к свойству $publicProp нашего тестового класса Example новый тег @Column:
Установка дополнительных библиотек
Для работы нам понадобятся некоторые дополнительные библиотеки. Установим их.
- Если у вас не установлено расширение PHP XSL, то Docblox сообщит вам о том, что документация в HTML-формате не может быть создана. Установить это расширение можно, например, так:
# apt-get install php5-xsl # apachectl restart (у кого стоит Apache)
- Для генерирования графа класса также следует установить Graphviz:
# apt-get install graphviz
- Для генерирования документации в формате PDF необходима библиотека wkhtmltopdf:
# apt-get install wkhtmltopdf
Промежуточный XML-файл с данными парсера
Нам понадобится тестовый пример, содержащий для начала уже знакомые нам @-теги PHP Documentor, чтобы понять структуру генерируемого XML-файла, которая на данный момент не документирована на официальном сайте проекта. Возьмем файл Example.php, содержащий класс Example:
/**
* Example class file short description.
*
* @package file.package
* @author Vania-pooh <vania-pooh@myemail.com>
* @link http://www.myexampleclass.com/
* @copyright Copyright © 2011 Vania-pooh
* @license http://www.gnu.org/licenses/old-licenses/lgpl-2.1.txt LGPL
*/
namespace \ExampleNS;
/**
* Example class short description.
*
* Example class long description.
* Lorem ipsum dolor sit amet, consectetur adipiscing elit.
* Nunc mollis leo felis, nec euismod nulla.
* Vivamus condimentum vehicula consequat.
*
* @author Vania-pooh <vania-pooh@myemail.com>
* @package class.package
* @since 1.0
*/
class Example extends ParentExample
{
/**
* @var string public property description. Defaults to 'publicValue'.
* @static
* @Column(type="string", length=32, unique=true, nullable=false)
*/
public static $publicProp = 'publicValue';
/**
* @var int private property description.
*/
private $privateProp = 1;
/**
* @var boolean protected property description.
*/
protected $protectedProp = false;
/**
* Public function short description.
*
* Public function long description.
* @param boolean $param1 param1 short description.
* @param string $param2 param2 short description.
*/
public function doIt($param1, $param2)
{
//...
}
}
Создадим простой файл конфигурации docblox.xml для Docblox, где явно укажем куда сохранять нужный нам XML-файл. Кроме того создадим в каталоге /src/example два каталога — docs и xml.Теперь запустим Docblox в каталоге /src/example:
$ cd /src/example
$ docblox run
Нужный нам файл structure.xml будет создан в указанной нами папке /src/example/xml/. Рассмотрим его поподробнее. Итак, типичный файл structure.xml имеет следующую структуру:<?xml version="1.0"?><project version="0.14.0" title="">
<!-- Атрибут hash содержит контрольную сумму файла, вычисленную по алгоритму MD5 -->
<file path="Example.php" hash="8c6b0d4bc263fcf83499f57f1dcd9aa6" package="file\package">
<!-- Если тег docblock размещен внутри тега file, то он описывает комментарий уровня файла -->
<docblock>
<description>Example class file short description.</description>
<long-description> </long-description>
<!-- Здесь идут описания @-тегов файла -->
<tag name="author" description="Vania-pooh <vania-pooh@myemail.com>"/>
<!-- … -->
</docblock>
<!-- Начало описания класса -->
<class final="false" abstract="false" line="24" namespace="ExampleNS" package="class\package">
<name>Example</name>
<extends>\ExampleNS\ParentExample</extends>
<full_name>\ExampleNS\Example</full_name>
<docblock>
<description>Example class short description.</description>
<long-description>Бла-бла-бла</long-description>
<tag name="author" description="Vania-pooh <vania-pooh@myemail.com>" line="12"/>
<tag name="package" description="class.package" line="12"/>
<tag name="since" description="1.0" line="12"/>
</docblock>
<!-- Описание открытого свойства -->
<property final="false" static="true" visibility="public" line="30" package="Default">
<name>$publicProp</name>
<default>publicValue</default>
<docblock> <!-- @-теги открытого свойства --></docblock>
</property>
<property final="false" static="false" visibility="private" line="35" package="Default">
<!-- @-теги закрытого свойства -->
</property>
<!-- Тут то же самое для защищенного свойства →
<!-- Описание метода -->
<method final="false" abstract="false" static="false" visibility="public" line="50" package="Default">
<name>doIt</name>
<docblock> <!-- @-теги открытого метода doIt() --></docblock>
<!-- Описание аргумента метода -->
<argument line="50">
<name>$param1</name>
<default/>
<type/>
</argument>
<argument line="50">
<name>$param2</name>
<!-- Тут все аналогично -->
</argument>
</method>
</class>
</file>
<package name="Default"/>
<!-- Тут перечисление других используемых пакетов -->
<namespace name="ExampleNS"/>
<marker>todo</marker>
<marker>fixme</marker>
</project>
Приведенный код не требует особых комментариев. Отмечу только, что все содержимое docblock-разметки всегда содержится внутри тегов <docblock></docblock>. Остальные теги описывают значения, полученные на основе анализа исполняемого кода, а не комментариев к нему. Что касается названия пакета, задаваемого тегом @package, то здесь при отсутствии этого тега используется значение параметра default-package-name из командной строки или файла docblox.xml. Если параметр не задан, то используется значение Default. Как видно, можно использовать различные названия пакетов для всего файла в целом, для класса и для отдельного свойства\метода.Использование тем
Docblox поддерживает создание различных тем отображения кода. При установке библиотеки при помощи PEAR темы располагаются в каталоге <PEAR_ROOT>/Docblox/data/themes, где <PEAR_ROOT> — место хранения исходных кодов всех установленных пакетов PEAR (например, в Ubuntu <PEAR_ROOT> это /usr/share/php/). Каждая тема располагается в отдельном каталоге и обязательно имеет в своем составе файл template.xml, в котором прописаны правила сборки документации. Файл состоит в основном из строчек вида:
<transformation query="действие" writer="какой встроенный класс выполняет действие" source="исходный файл для обработки" artifact="имя записываемого файла или каталога" />
Примеры правил:
query | writer | source | artifact |
---|---|---|---|
copy | FileIO | Что скопировать | Куда скопировать |
- | xsl | XSL-шаблон | Готовый HTML-файл |
- | Graph | Граф чего рисовать | Имя файла svg с графом |
- | Имя файла HTML | Имя файла PDF |
Генерирование документации в формате PDF
Генерирование документации в формат PDF также не представляет сложностей. Для этого нужно просто использовать стандартную тему pdf в файле конфигурации docblox.xml:
<transformations>
<template name="pdf" />
</transformations>
После запуска Docblox вы увидите, что в папке /src/example/docs/ (если в файле конфигурации не указано куда сохранять готовую документацию, то по-умолчанию в текущей директории для этого будет создан каталог output) появился набор HTML-страниц и требуемый файл apidocs.pdf.Но мы ведь не просили генерировать HTML! Все правильно, однако, Docblox использует библиотеку wkhtmltopdf, которая умеет преобразовывать только HTML в PDF, поэтому приходится создавать HTML-страницы, которые затем преобразуются в единый PDF-файл. Если вы посмотрите файл index.html из той же папки, то увидите, что он имеет точно такой же вид, что и полученный PDF-файл. Таким образом, модифицируя оформление HTML-файлов, вы можете создавать документацию в формате PDF произвольного внешнего вида. Это очень удобный подход, позволяющий создавать сайт проекта и его документацию из одних и тех же графических элементов и таблиц стилей.Генерирование UML-графа
Для генерирования UML-графа необходимо добавить правило в настройки используемой темы (template.xml) следующим образом:
<transformation query="" writer="Graph" source="Class" artifact="filename.svg" />
После запуска Docblox в /src/example/docs/ вы получите файл filename.svg, содержащий требуемую диаграмму класса.Это позволяет встраивать диаграмму класса в файл с документацией.
Поддержка @-тегов Doctrine
Начиная с версии 0.14 Docblox поддерживает @-теги используемые для документирования применения всем известной ORM Doctrine. Добавим к свойству $publicProp нашего тестового класса Example новый тег @Column:
/**
* @var string public property description. Defaults to 'publicValue'.
* @static
* @Column(type="string", length=32, unique=true, nullable=false)
*/
После обработки файла в structure.xml появится новый блок:
<tag name="Column" description="Column" plugin="doctrine" link="http://www.doctrine-project.org/docs/orm/2.1/en/reference/annotations-reference.html#annref-column" content="type="string", length=32, unique=true, nullable=false" line="26">
<argument field-name="type">"string"</argument>
<argument field-name="length">32</argument>
<argument field-name="unique">true</argument>
<argument field-name="nullable">false</argument>
</tag>
Как видно, Docblox умеет автоматически добавлять ссылку на соответствующий раздел документации Doctrine и выделять из нотации тега передаваемые им параметры наподобие type, length и других. Добавление поддержки @-тегов Doctrine сделало Dockblox еще на ступеньку выше. Будем надеяться, что развитие этого полезного проекта будет таким же успешным и в дальнейшем.Ссылки
- http://www.graphviz.org/ — официальный сайт Graphviz
- http://code.google.com/p/wkhtmltopdf/ — страница wkhtmltopdf>
- http://www.doctrine-project.org/docs/orm/2.0/en/reference/annotations-reference.html — описание @-тегов Doctrine
- http://ru.wikipedia.org/wiki/XSL — подробнее об XSL
- http://php.net/xsl — PHP класс для работы с XSL