Pull to refresh

Docblox — некоторые нововведения

Reading time 7 min
Views 2.1K
Эта статья более подробно рассматривает некоторые нововведения, предложенные Docblox,- системой документирования для PHP 5.3+. Для понимания некоторых вещей необходимо прочитать предыдущую статью. Для простоты в качестве каталога с тестовыми исходными кодами я использовал /src/example/ (/src— симлинк на реальный каталог с моими исходными кодами).

Установка дополнительных библиотек


Для работы нам понадобятся некоторые дополнительные библиотеки. Установим их.
  1. Если у вас не установлено расширение PHP XSL, то Docblox сообщит вам о том, что документация в HTML-формате не может быть создана. Установить это расширение можно, например, так:
    # apt-get install php5-xsl
    # apachectl restart (у кого стоит Apache)
  2. Для генерирования графа класса также следует установить Graphviz:
    # apt-get install graphviz
  3. Для генерирования документации в формате 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 с графом
- pdf Имя файла HTML Имя файла PDF
Кроме template.xml любая тема содержит XSL-шаблоны страниц, каскадные таблицы стилей, js-сценарии и т.п. Таким образом, если вы знакомы с XSL-шаблонами, вам не составит труда создать новую тему отображения документации, зная структуру файла structure.xml.

Генерирование документации в формате PDF


Генерирование документации в формат PDF также не представляет сложностей. Для этого нужно просто использовать стандартную тему pdf в файле конфигурации docblox.xml:
<transformations> 
  <template name="pdf" /> 
</transformations>
После запуска Docblox вы увидите, что в папке /src/example/docs/ (если в файле конфигурации не указано куда сохранять готовую документацию, то по-умолчанию в текущей директории для этого будет создан каталог output) появился набор HTML-страниц и требуемый файл apidocs.pdf.Итоговый файл 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, содержащий требуемую диаграмму класса.UML-диаграмма класса
Это позволяет встраивать диаграмму класса в файл с документацией.

Поддержка @-тегов 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 еще на ступеньку выше. Будем надеяться, что развитие этого полезного проекта будет таким же успешным и в дальнейшем.

Ссылки

Tags:
Hubs:
+19
Comments 2
Comments Comments 2

Articles