The Helios Blogs

Bridging the Cultural & Communication Gap

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

[php]$ composer.phar install ”[/php]

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

[php]$ php sami.php[/php]

Configuration

Before generating documentation, you must create a configuration file.

[php]<?php

return new Sami\Sami(‘/path/to/symfony/src’);
[/php]

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)

[php] 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);

[/php]

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

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

[/php]

Configuration for different versions:

[php] <?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,
));

[/php]

Rendering

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

[php]$ php sami.php update /path/to/config.php[/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]$ php sami.php update /path/to/config.php -v[/php]

That’s all , enjoy the new gained knowledge.

Leave a Reply

Your email address will not be published. Required fields are marked *