Docblox - some innovations

This article takes a closer look at some of the innovations proposed by Docblox , the documentation system for PHP 5.3+. To understand some of the things you need to read the previous article . For simplicity, I used / src / example / ( / src - a symlink to the real directory with my source codes) as a directory with test source codes.

Install additional libraries

To work we need some additional libraries. Install them.

If you do not have the PHP XSL extension installed, Docblox will notify you that HTML documentation cannot be created. You can install this extension, for example, like this:
```
# apt-get install php5-xsl # apachectl restart (   Apache) 
```
To generate a class graph, you should also install Graphviz:
```
 # apt-get install graphviz 
```
To generate PDF documentation, you need the wkhtmltopdf library:
```
 # apt-get install wkhtmltopdf 
```

Intermediate XML file with parser data

We will need a test case containing, for a start, the Documentor @ -tates already familiar to us to understand the structure of the generated XML file, which is currently not documented on the official project website. Take the Example.php file containing the Example class:

 /** * 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) { //... } }

Create a simple docblox.xml configuration file for Docblox, where you explicitly specify where to save the XML file we need. In addition, we will create two directories in the / src / example directory - docs and xml.

Configuration file and directory structure

Now run Docblox in the / src / example directory:

 $ cd /src/example $ docblox run

The structure.xml file we need will be created in the / src / example / xml / folder that we specified. Consider it in more detail. So, the typical structure.xml file has the following structure:

 <?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>

The above code does not require special comments. I will only note that the entire contents of the docblock markup is always contained within the <docblock> </ docblock> tags . The remaining tags describe the values obtained on the basis of the analysis of the executable code, and not comments to it. As for the name of the package specified by the @package tag, here in the absence of this tag, the value of the default-package-name parameter from the command line or the docblox.xml file is used . If the parameter is not specified, the Default value is used. As you can see, you can use different package names for the entire file as a whole, for the class and for a separate property \ method.

Using themes

Docblox supports the creation of various code display themes. When installing the library using PEAR, the themes are located in the directory <PEAR_ROOT> / Docblox / data / themes, where <PEAR_ROOT> is where the source codes of all installed PEAR packages are stored (for example, in Ubuntu <PEAR_ROOT> is / usr / share / php / ) . Each topic is located in a separate directory and it necessarily contains the file template.xml , which contains the rules for assembling documentation. The file consists mainly of lines of the form:

 <transformation query="" writer="    " source="   " artifact="    " />

Examples of rules:

query	writer	source	artifact
copy	FileIO	What to copy	Where to copy
-	xsl	Xsl template	Ready HTML file
-	Graph	Count of what to draw	File name svg with graph
-	pdf	HTML file name	PDF file name

In addition to template.xml, any theme contains XSL page templates, cascading style sheets, js scripts, etc. Thus, if you are familiar with XSL templates, it will not be difficult for you to create a new topic for displaying documentation, knowing the structure of the structure.xml file.
')

PDF documentation generation

Documentation generation in PDF format is also easy. To do this, simply use the standard pdf theme in the docblox.xml configuration file :

 <transformations> <template name="pdf" /> </transformations>

After running Docblox, you will see that in the / src / example / docs / folder (if the configuration file does not indicate where to save the finished documentation, then by default the output directory will be created in the current directory for this) and the required file apidocs.pdf. PDF

But we did not ask to generate HTML! Everything is correct, however, Docblox uses the wkhtmltopdf library, which can only convert HTML to PDF, so you have to create HTML pages that are then converted into a single PDF file. If you look at the index.html file from the same folder, you will see that it looks exactly the same as the resulting PDF file. Thus, modifying the design of HTML-files, you can create documentation in PDF format of any appearance. This is a very convenient approach that allows you to create a project site and its documentation from the same graphic elements and style sheets.

Generating a UML graph

To generate a UML graph, you need to add a rule to the settings of the theme used (template.xml) as follows:

 <transformation query="" writer="Graph" source="Class" artifact="filename.svg" />

After running Docblox in / src / example / docs /, you will get the file filename.svg containing the required class diagram. UML-

This allows you to embed a class diagram in the documentation file.

Doctrine @tags support

Starting from version 0.14 Docblox supports @ -tags used to document the application of the well-known ORM Doctrine to everyone. Add a new @Column tag to the $ publicProp property of our test class Example:

 /** * @var string public property description. Defaults to 'publicValue'. * @static * @Column(type="string", length=32, unique=true, nullable=false) */

After processing the file in structure.xml, a new block will appear:

 <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>

As you can see, Docblox can automatically add a link to the corresponding Doctrine section of the documentation and extract from the tag notation the parameters passed to them like type, length and others. Adding support for Doctrine @tags made Dockblox one step higher. Let us hope that the development of this useful project will be equally successful in the future.