PHP API documentation generator

There are lots of document generator out there , many of them quite good. Perhaps the best of them would be phpDocumentor version 2. Lets have a look why Sami is different from phpdocumentor.

• It uses Twig for templating.
• It is able to manage versions of your code to generate documentation for all of them in a single tree (without the overhead of re-parsing everything for each version of course).
• It uses a PHP file for configuration to give a very flexible way of tweaking the API generation.
• It uses a dependency injection container (Pimple) to let you override any internal class.
• It only works with PHP 5.3 (but it can generate documentation for PHP 5.2 projects).
• It uses the excellent PHP Parser project for PHP code parsing.

Installation:

Get Sami from Github (or integrate it as a dependency in your project Composer file

Sami uses Composer to manage its dependencies so just run the composer

$ composer.phar install ”

To confirm everything worked fine just execute the sami.php file.

$ php sami.php

Configuration

Before generating documentation, you must create a configuration file.

<?php

return new Sami\Sami('/path/to/symfony/src');

The first argument of constructor is the path to the code to generate documentation for. One valid method is to use PHP iterator (for that use the Symfony Finder class)

use Sami\Sami;
use Symfony\Component\Finder\Finder;
 
$iterator = Finder::create()
    ->files()
    ->name('*.php')
    ->exclude('Resources')
    ->exclude('Tests')
    ->in('/path/to/symfony/src')
;
 
return new Sami($iterator);

The Sami constructor optionally takes an array of options as a second argument:

return new Sami($iterator, array(
    'theme'                => 'symfony',
    'title'                => 'Symfony2 API',
    'build_dir'            => __DIR__.'/build',
    'cache_dir'            => __DIR__.'/cache',
    'default_opened_level' => 2,
));

Configuration for different versions:

<?php
 
use Sami\Sami;
use Sami\Version\GitVersionCollection;
use Symfony\Component\Finder\Finder;

$iterator = Finder::create()
    ->files()
    ->name('*.php')
    ->exclude('Resources')
    ->exclude('Tests')
    ->in($dir = '/path/to/symfony/src')
;
 
// generate documentation for all v2.0.* tags, the 2.0 branch, and the master one
$versions = GitVersionCollection::create($dir)
    ->addFromTags('v2.0.*')
    ->add('2.0', '2.0 branch')
    ->add('master', 'master branch')
;
 
return new Sami($iterator, array(
    'theme'                => 'symfony',
    'versions'             => $versions,
    'title'                => 'Symfony2 API',
    'build_dir'            => __DIR__.'/../build/sf2/%version%',
    'cache_dir'            => __DIR__.'/../cache/sf2/%version%',
    'default_opened_level' => 2,
));

Rendering

Now that we have a configuration file, let’s generate the API documentation:

$ php sami.php update /path/to/config.php

The generated documentation can be found under the configured build/ directory (note that the client side search engine does not work on Chrome due to JavaScript execution restriction — it works fine in Firefox).

Sami also detects problems in your phpdoc and can tell you what you need to fix if you add the -v option:

$ php sami.php update /path/to/config.php -v

That’s all , enjoy the new gained knowledge.