Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

https://github.com/FriendsOfPHP/Sami

An API documentation generator
https://github.com/FriendsOfPHP/Sami

Last synced: 25 days ago
JSON representation

An API documentation generator

Lists

README 

        
Sami: an API documentation generator

====================================



**WARNING**: Sami is not supported nor maintained anymore. Feel free to fork.



Curious about what Sami generates? Have a look at the `Symfony API`_.



Installation

------------



.. caution::



    Sami requires **PHP 7**.



Get Sami as a `phar file`_:



.. code-block:: bash



    $ curl -O http://get.sensiolabs.org/sami.phar



Check that everything worked as expected by executing the ``sami.phar`` file

without any arguments:



.. code-block:: bash



    $ php sami.phar



.. note::



    Installing Sami as a regular Composer dependency is NOT supported. Sami is

    a tool, not a library. As such, it should be installed as a standalone

    package, so that Sami's dependencies do not interfere with your project's

    dependencies.



Configuration

-------------



Before generating documentation, you must create a configuration file. Here is

the simplest possible one:



.. code-block:: php



    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:



.. code-block:: php



    return new Sami($iterator, array(

        'theme'                => 'symfony',

        'title'                => 'Symfony2 API',

        'build_dir'            => __DIR__.'/build',

        'cache_dir'            => __DIR__.'/cache',

        'remote_repository'    => new GitHubRemoteRepository('username/repository', '/path/to/repository'),

        'default_opened_level' => 2,

    ));



And here is how you can configure different versions:



.. code-block:: php



    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%',

        'remote_repository'    => new GitHubRemoteRepository('symfony/symfony', dirname($dir)),

        'default_opened_level' => 2,

    ));



To generate documentation for a PHP 5.2 project, simply set the

``simulate_namespaces`` option to ``true``.



You can find more configuration examples under the ``examples/`` directory of

the source code.



Sami only documents the public API (public properties and methods); override

the default configured ``filter`` to change this behavior:



.. code-block:: php