Docblox - PHP 5.3+ Compatible Documentation System

During the next Phing update using PEAR, I noticed a list of additional dependencies and decided to visit the sites of those projects whose names did not tell me anything. Among other things, I found one promising project that I would like to share with you. I present to you Docblox - a new system for documenting PHP applications that develops the ideas embodied in the well-known PHP Documentor . At the moment, according to the PEAR notation, the project is in beta testing, but it is already used in the development of projects such as Zend Framework , Phing , Fuel and some others.

New features compared with PHP Documentor :

1. Namespace support
2. Some new @ -takes: api , magic , @ property-read, @ property-write, @throws
3. Ability to inherit method descriptions in child classes (when adding an empty docblock, descriptions are copied from the parent class \ interface)
4. Support for simple text formatting like wiki markup (markdown), including the creation of lists
5. Tracking changed files (processing accelerates because only changed files are viewed)
6. Two-step documentation generation through an intermediate XML file, on the basis of which HTML pages can be generated. The content of the XML file contains all the information extracted from the source code, and can be used by the programmer at his discretion.
7. Support for XML files with a configuration such as build.xml for Phing, allowing you to generate documentation by running the docblox command without parameters
8. Support for themes and content display templates
9. Ability to add custom classes for exporting XML data to a file of arbitrary format
10. PDF generation capability (additional library wkhtmltopdf is required , written using WebKit to convert HTML → PDF)
11. Ability to generate a UML-like graph for each class (Graphviz required)

Installation:

The project has its own PEAR channel, so the installation is done primitively simple:

# pear channel-discover pear.docblox-project.org # pear channel-discover pear.michelf.com # pear install DocBlox/DocBlox-beta (-beta   ,  beta-     ) 

Documentation generation:

 $ docblox run 

It is executed in the source folder when it contains the file docblox.dist.xml or docblox.xml . Otherwise, an error is issued.

 $ docblox run --config /path/to/docblox.xml 

If the configuration file is not located in the current directory.
')

 $ docblox run --filename /path/to/file1,/path/to/file2 

If you need to list individual files.

 $ docblox run --directory /path/to/src1,/path/to/src2 --target /path/where/to/save/docs 

You can explicitly specify the directories to search for files with source codes and the directory where the finished documentation will be written. All specified directories must exist.

 $ docblox run --help 

You can see some other Docblox options by calling Help.

Example configuration file docblox.dist.xml or 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> 

References:

• http://www.docblox-project.org/ - project site
• http://demo.docblox-project.org/ - an example of the generated documentation (each folder uses a different appearance of the documentation view)
• http://github.com/mvriel/docblox - a repository on GitHub
• http://twitter.com/docblox - microblogging project on Twitter

At the moment, the most recent version of Docblox is 0.13.3, which was released at the end of August 2011. According to reports from the site, version 0.14 is being prepared for release.