Today is my "let open source some of my private Github repositories" day, and more specifically, I'm releasing a bunch of code related to documentation.
Earlier today, I've released the Sphinx extensions I'm using to generate the Symfony documentation.
And now, I'm releasing my API documentation generator. Yes, I know that PHP already has a bunch of such generators, but I started to work on this project several years ago, when the only viable option was the old phpdocumentor.
Nowadays, phpDocumentor version 2 is probably the best option out there as it has a good architecture, it works fine, it is extensible, and quite a few big PHP projects is already using it. And that's fine. I don't want to compete with it, I don't want to replace it, I'm just open sourcing some code used by
Symfony, Twig, and Silex because I'm not comfortable with closed-source software. And to be totally honest and transparent, I have not released the code before because it was not "good
enough".
With this disclaimer out of the way, let's see what makes Sami "different" (compared to phpdocumentor)?
-
It uses a PHP file for configuration to give a very flexible way of tweaking the API generation;
-
It uses Twig for templating;
-
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;
-
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).
Curious about what Sami generates? Have a look at the Symfony API.
Installation
First, get Sami from Github (or integrate it as a dependency in your project Composer file -- you are using Composer, right?):
https://github.com/fabpot/Sami
You can also download an archive from Github.
As Sami uses Composer to manage its dependencies, installing it is a matter of running composer:
$ composer.phar install
Check that everything worked as expected by executing the sami.php file without any arguments:
$ php sami.php
Configuration
Before generating documentation, you must create a configuration file. Here is the simplest possible one:
<?php
return new Sami\Sami('/path/to/symfony/src');
The configuration file must return an instance of Sami\Sami and the first argument of the constructor is the path to the code you want to generate documentation for.
Actually, instead of a directory, you can use any valid PHP iterator (and for that matter any instance of 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
Truncated by Planet PHP, read more at the original (another 8447 bytes)
