При очередном обновлении Phing с помощью PEAR я обратил внимание на список дополнительных зависимостей и решил посетить сайты тех проектов, названия которых мне ничего не говорили. Среди прочего я нашел один многообещающий проект, которым бы и хотел с вами поделиться. Представляю вам Docblox — новую систему документирования PHP-приложений, развивающую идеи, заложенные во всем известном PHP Documentor'е. На данный момент согласно нотации PEAR проект находится в стадии бета-тестирования, но уже используется при разработке таких проектов, как Zend Framework, Phing, Fuel и некоторых других.

Новые возможности по сравнению с PHP Documentor:

  1. Поддержка пространств имен
  2. Некоторые новые @-теги: api, magic, @property-read, @property-write, @throws
  3. Возможность наследования описания методов в дочерних классах (при добавлении пустого docblock'а описания копируются из родительского класса\интерфейса)
  4. Поддержка простого форматирования текста наподобие Вики-разметки (markdown), в том числе создание списков
  5. Отслеживание изменившихся файлов (обработка ускоряется, так как просматриваются только изменившиеся файлы)
  6. Двухступенчатая генерация документации через промежуточный XML-файл, на основе которого могут генерироваться HTML-страницы. Содержимое XML-файла содержит всю информацию, извлеченную из исходных кодов, и может быть использовано программистом по своему усмотрению.
  7. Поддержка XML-файлов с конфигурацией наподобие build.xml для Phing, позволяющих генерировать документацию запуском команды docblox без параметров
  8. Поддержка тем и шаблонов отображения содержимого
  9. Возможность добавления собственных классов для экспорта XML-данных в файл произвольного формата
  10. Возможность генерирования PDF (требуется дополнительная библиотека wkhtmltopdf, написанная с использованием WebKit для конвертации HTML → PDF)
  11. Возможность генерирования 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>

Ссылки:

На данный момент наиболее свежая версия Docblox — 0.13.3, вышедшая в конце августа 2011. Судя по сообщениям с сайта готовится к выходу версия 0.14.