https://github.com/FriendsOfPHP/Sami

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

Last synced: 3 months ago
JSON representation

An API documentation generator

• Host: GitHub
• URL: https://github.com/FriendsOfPHP/Sami
• Owner: FriendsOfPHP
• License: mit
• Archived: true
• Created: 2012-05-15T11:20:10.000Z (over 12 years ago)
• Default Branch: master
• Last Pushed: 2018-09-13T16:44:29.000Z (over 6 years ago)
• Last Synced: 2024-04-14T11:54:48.346Z (9 months ago)
• Language: PHP
• Size: 740 KB
• Stars: 2,000
• Watchers: 87
• Forks: 292
• Open Issues: 41
• Metadata Files:
  • Readme: README.rst
  • Changelog: CHANGELOG
  • License: LICENSE

Awesome Lists containing this project

• php-awesome - Sami - 项目文档生成工具 (类库 / API文档)

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