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]<?phpreturn 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] <?phpuse 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]$ 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.