При очередном обновлении Phing с помощью PEAR я обратил внимание на список дополнительных зависимостей и решил посетить сайты тех проектов, названия которых мне ничего не говорили. Среди прочего я нашел один многообещающий проект, которым бы и хотел с вами поделиться. Представляю вам Docblox — новую систему документирования PHP-приложений, развивающую идеи, заложенные во всем известном PHP Documentor'е. На данный момент согласно нотации PEAR проект находится в стадии бета-тестирования, но уже используется при разработке таких проектов, как Zend Framework, Phing, Fuel и некоторых других.
Проект имеет собственный канал PEAR, поэтому установка делается примитивно просто:
Выполняется в папке с исходными кодами при наличии в ней файла docblox.dist.xml или docblox.xml. В противном случае выдается ошибка.
Если конфигурационный файл располагается не в текущем каталоге.
Если нужно перечислить отдельные файлы.
Можно явно указать директории поиска файлов с исходными кодами и директорию, куда будет записана готовая документация. Все указываемые каталоги должны существовать.
Некоторые другие опции Docblox вы можете посмотреть, вызвав справку.
Новые возможности по сравнению с PHP Documentor:
- Поддержка пространств имен
- Некоторые новые @-теги: api, magic, @property-read, @property-write, @throws
- Возможность наследования описания методов в дочерних классах (при добавлении пустого docblock'а описания копируются из родительского класса\интерфейса)
- Поддержка простого форматирования текста наподобие Вики-разметки (markdown), в том числе создание списков
- Отслеживание изменившихся файлов (обработка ускоряется, так как просматриваются только изменившиеся файлы)
- Двухступенчатая генерация документации через промежуточный XML-файл, на основе которого могут генерироваться HTML-страницы. Содержимое XML-файла содержит всю информацию, извлеченную из исходных кодов, и может быть использовано программистом по своему усмотрению.
- Поддержка XML-файлов с конфигурацией наподобие build.xml для Phing, позволяющих генерировать документацию запуском команды docblox без параметров
- Поддержка тем и шаблонов отображения содержимого
- Возможность добавления собственных классов для экспорта XML-данных в файл произвольного формата
- Возможность генерирования PDF (требуется дополнительная библиотека wkhtmltopdf, написанная с использованием WebKit для конвертации HTML → PDF)
- Возможность генерирования UML-подобного графа для каждого класса (требуется Graphviz)
Установка:
Проект имеет собственный канал PEAR, поэтому установка делается примитивно просто:
# pear channel-discover pear.docblox-project.org
# pear channel-discover pear.michelf.com
# pear install DocBlox/DocBlox-beta (-beta нужна для того, чтобы beta-версия установилась без сообщений об ошибке)
Генерирование документации:
$ docblox run
Выполняется в папке с исходными кодами при наличии в ней файла docblox.dist.xml или docblox.xml. В противном случае выдается ошибка.
$ docblox run --config /path/to/docblox.xml
Если конфигурационный файл располагается не в текущем каталоге.
$ docblox run --filename /path/to/file1,/path/to/file2
Если нужно перечислить отдельные файлы.
$ docblox run --directory /path/to/src1,/path/to/src2 --target /path/where/to/save/docs
Можно явно указать директории поиска файлов с исходными кодами и директорию, куда будет записана готовая документация. Все указываемые каталоги должны существовать.
$ docblox run --help
Некоторые другие опции Docblox вы можете посмотреть, вызвав справку.
Пример файла конфигурации docblox.dist.xml или docblox.xml:
<?xml version="1.0" encoding="UTF-8" ?>
<docblox>
<!-- 1) Список просматриваемых\игнорируемых файлов и директорий (поддерживает маски * и ?) -->
<files>
<directory>src</directory>
<directory>tes??</directory>
<file>test.php</file>
<file>bin/*</file>
<ignore>test/*</ignore>
</files>
<!-- 2) Все, что касается парсера документации -->
<parser>
<!-- 2.1) Куда сохранять промежуточный XML-файл -->
<target>src/docs/xml</target>
<!-- 2.2) Если не указан тег @package используется такое имя пакета -->
<default-package-name>core</default-package-name>
<!-- 2.3) Позволяет указать дополнительные комбинации символов, воспринимаемые парсером, как служебные -->
<markers>
<item>TODO</item>
<item>FIXME</item>
</markers>
<!-- 2.4) Парсер просматривает файлы только с такими расширениями -->
<extensions>
<extension>php</extension>
<extension>php3</extension>
<extension>phtml</extension>
</extensions>
</parser>
<!-- 3) Все, что касается преобразования промежуточного XML-файла в понятный человеку формат -->
<transformer>
<!-- 3.1) Куда записывать сгенерированную документацию -->
<target>src/docs/html</target>
<!-- 3.2) Позволяет присоединить ссылку на стороннюю документацию класса с префиксом Std_Class-->
<external-class-documentation>
<prefix>Std_Class</prefix>
<uri>http://external-project.org/docs/latest/</uri>
</external-class-documentation>
</transformer>
<!-- 4) Какие шаблоны оформления используются при генерации документации -->
<transformations>
<template name="Crystal-Blue" />
</transformations>
<!-- 5) Настройки ведения логов -->
<logging>
<!-- 5.1) Уровень информативности логов (такой же набор уровней, как в настройках PHP) -->
<level>warn</level>
<!-- 5.2) Пути записи основного лога (default) и лога с отладочной информацией (errors). Шаблон {APP_ROOT} заменяется на корневой каталог исходных кодов, {DATE} — на текущую дату -->
<paths>
<default>{APP_ROOT}/data/log/{DATE}.log</default>
<errors>{APP_ROOT}/data/log/{DATE}.errors.log</errors>
</paths>
</logging>
</docblox>
Ссылки:
- http://www.docblox-project.org/ — сайт проекта
- http://demo.docblox-project.org/ — пример сгенерированной документации (в каждой папке используется разный внешний вид представления документации)
- http://github.com/mvriel/docblox — репозиторий на GitHub
- http://twitter.com/docblox — микроблог проекта в Твиттере