Permalink
Browse files

added files

  • Loading branch information...
fabpot committed May 15, 2012
0 parents commit aa8d08664f4b5c1d733e882383add048e3301476
Showing with 7,679 additions and 0 deletions.
  1. +2 −0 .gitignore
  2. +6 −0 CHANGELOG
  3. +19 −0 LICENSE
  4. +192 −0 README.md
  5. +42 −0 Sami/Console/Application.php
  6. +228 −0 Sami/Console/Command/Command.php
  7. +62 −0 Sami/Console/Command/ParseCommand.php
  8. +61 −0 Sami/Console/Command/RenderCommand.php
  9. +54 −0 Sami/Console/Command/UpdateCommand.php
  10. +47 −0 Sami/ErrorHandler.php
  11. +53 −0 Sami/Indexer.php
  12. +25 −0 Sami/Message.php
  13. +66 −0 Sami/Parser/ClassTraverser.php
  14. +65 −0 Sami/Parser/ClassVisitor/InheritdocClassVisitor.php
  15. +19 −0 Sami/Parser/ClassVisitorInterface.php
  16. +40 −0 Sami/Parser/CodeParser.php
  17. +152 −0 Sami/Parser/DocBlockParser.php
  18. +28 −0 Sami/Parser/Filter/DefaultFilter.php
  19. +25 −0 Sami/Parser/Filter/FilterInterface.php
  20. +28 −0 Sami/Parser/Filter/SymfonyFilter.php
  21. +34 −0 Sami/Parser/Filter/TrueFilter.php
  22. +84 −0 Sami/Parser/Node/DocBlockNode.php
  23. +269 −0 Sami/Parser/NodeVisitor.php
  24. +99 −0 Sami/Parser/Parser.php
  25. +139 −0 Sami/Parser/ParserContext.php
  26. +82 −0 Sami/Parser/Transaction.php
  27. +430 −0 Sami/Project.php
  28. +397 −0 Sami/Reflection/ClassReflection.php
  29. +53 −0 Sami/Reflection/ConstantReflection.php
  30. +54 −0 Sami/Reflection/HintReflection.php
  31. +237 −0 Sami/Reflection/LazyClassReflection.php
  32. +171 −0 Sami/Reflection/MethodReflection.php
  33. +96 −0 Sami/Reflection/ParameterReflection.php
  34. +105 −0 Sami/Reflection/PropertyReflection.php
  35. +153 −0 Sami/Reflection/Reflection.php
  36. +107 −0 Sami/Renderer/Diff.php
  37. +62 −0 Sami/Renderer/Index.php
  38. +210 −0 Sami/Renderer/Renderer.php
  39. +72 −0 Sami/Renderer/Theme.php
  40. +67 −0 Sami/Renderer/ThemeSet.php
  41. +133 −0 Sami/Renderer/TwigExtension.php
  42. +33 −0 Sami/Resources/themes/default/classes.twig
  43. +3 −0 Sami/Resources/themes/default/index.twig
  44. +21 −0 Sami/Resources/themes/default/layout/base.twig
  45. +13 −0 Sami/Resources/themes/default/layout/frame.twig
  46. +11 −0 Sami/Resources/themes/default/layout/layout.twig
  47. +30 −0 Sami/Resources/themes/default/layout/page.twig
  48. +59 −0 Sami/Resources/themes/default/macros.twig
  49. +21 −0 Sami/Resources/themes/default/manifest.yml
  50. +48 −0 Sami/Resources/themes/default/namespace.twig
  51. +26 −0 Sami/Resources/themes/default/namespaces.twig
  52. +213 −0 Sami/Resources/themes/default/pages/class.twig
  53. +28 −0 Sami/Resources/themes/default/pages/classes.twig
  54. +41 −0 Sami/Resources/themes/default/pages/index.twig
  55. +24 −0 Sami/Resources/themes/default/pages/interfaces.twig
  56. +49 −0 Sami/Resources/themes/default/pages/namespace.twig
  57. +21 −0 Sami/Resources/themes/default/pages/namespaces.twig
  58. +14 −0 Sami/Resources/themes/default/pages/opensearch.twig
  59. +212 −0 Sami/Resources/themes/default/stylesheet.css
  60. +2 −0 Sami/Resources/themes/enhanced/README.md
  61. +214 −0 Sami/Resources/themes/enhanced/css/main.css
  62. +427 −0 Sami/Resources/themes/enhanced/css/panel.css
  63. +53 −0 Sami/Resources/themes/enhanced/css/reset.css
  64. BIN Sami/Resources/themes/enhanced/i/arrows.png
  65. BIN Sami/Resources/themes/enhanced/i/loader.gif
  66. BIN Sami/Resources/themes/enhanced/i/results_bg.png
  67. BIN Sami/Resources/themes/enhanced/i/tree_bg.png
  68. +3 −0 Sami/Resources/themes/enhanced/index.twig
  69. +19 −0 Sami/Resources/themes/enhanced/js/jquery-1.3.2.min.js
  70. +651 −0 Sami/Resources/themes/enhanced/js/searchdoc.js
  71. +4 −0 Sami/Resources/themes/enhanced/layout/page.twig
  72. +18 −0 Sami/Resources/themes/enhanced/manifest.yml
  73. +80 −0 Sami/Resources/themes/enhanced/panel.twig
  74. +39 −0 Sami/Resources/themes/enhanced/search_index.twig
  75. +17 −0 Sami/Resources/themes/enhanced/tree.twig
  76. +157 −0 Sami/Sami.php
  77. +84 −0 Sami/Store/JsonStore.php
  78. +28 −0 Sami/Store/StoreInterface.php
  79. +133 −0 Sami/Tests/Parser/DocBlockParserTest.php
  80. +80 −0 Sami/Tree.php
  81. +112 −0 Sami/Version/GitVersionCollection.php
  82. +28 −0 Sami/Version/SingleVersionCollection.php
  83. +56 −0 Sami/Version/Version.php
  84. +98 −0 Sami/Version/VersionCollection.php
  85. +30 −0 composer.json
  86. +95 −0 composer.lock
  87. +29 −0 examples/sf2.php
  88. +26 −0 examples/swiftmailer.php
  89. +10 −0 examples/twig.php
  90. +18 −0 examples/zf2.php
  91. +19 −0 phpunit.xml.dist
  92. +14 −0 sami.php
@@ -0,0 +1,2 @@
vendor
composer.phar
@@ -0,0 +1,6 @@
CHANGELOG
=========
* 0.8 (2012-05-15)
* initial Open-Source version
19 LICENSE
@@ -0,0 +1,19 @@
Copyright (c) 2010-2012 Fabien Potencier
Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is furnished
to do so, subject to the following conditions:
The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
THE SOFTWARE.
192 README.md
@@ -0,0 +1,192 @@
Sami: an API documentation generator
====================================
Curious about what Sami generates? Have a look at the [Symfony
API](http://api.symfony.com/).
Installation
------------
First, get Sami from [Github](https://github.com/fabpot/Sami) (or integrate it
as a dependency in your project [Composer](packagist.org/fabpot/Sami) file --
you are using [Composer](http://getcomposer.org/), right?):
https://github.com/fabpot/Sami
You can also download an [archive](https://github.com/fabpot/Sami/downloads)
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](http://symfony.com/doc/current/components/finder.html) 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);
The `Sami` constructor optionally takes an array of options as a second
argument:
return new Sami($iterator, array(
'theme' => 'symfony',
'title' => 'Symfony2 API',
'build_dir' => __DIR__.'/build',
'cache_dir' => __DIR__.'/cache',
'default_opened_level' => 2,
));
And here is how you can configure different versions:
<?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,
));
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.
Rendering
---------
Now that we have a configuration file, let's generate the API documentation:
$ php sami.php update /path/to/config.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).
By default, Sami is configured to run in "incremental" mode. It means that
when running the `update` command, Sami only re-generates the files that needs
to be updated based on what has changed in your code since the last execution.
Sami also detects problems in your phpdoc and can tell you what you need to
fix if you add the `-v` option:
$ php sami.php update /path/to/config.php -v
Creating a Theme
----------------
If the default themes do not suit your needs, you can very easily create a new
one, or just override an existing one.
A theme is just a directory with a `manifest.yml` file that describes the
theme (this is a YAML file):
name: symfony
parent: enhanced
The above configuration creates a new `symfony` theme based on the `enhanced`
built-in theme. To override a template, just create a file with the same name
as the original one. For instance, here is how you can extend the default
class template to prefix the class name with "Class " in the class page title:
{# pages/class.twig #}
{% extends 'default/pages/class.twig' %}
{% block title %}Class {{ parent() }}{% endblock %}
If you are familiar with Twig, you will be able to very easily tweak every
aspect of the templates as everything has been well isolated in named Twig
blocks.
A theme can also add more templates and static files. Here is the manifest for
the default theme:
name: default
static:
'stylesheet.css': 'stylesheet.css'
global:
'index.twig': 'index.html'
'namespaces.twig': 'namespaces-frame.html'
'classes.twig': 'classes-frame.html'
'pages/opensearch.twig': 'opensearch.xml'
'pages/index.twig': 'doc-index.html'
'pages/namespaces.twig': 'namespaces.html'
'pages/interfaces.twig': 'interfaces.html'
'pages/classes.twig': 'classes.html'
namespace:
'namespace.twig': '%s/namespace-frame.html'
'pages/namespace.twig': '%s.html'
class:
'pages/class.twig': '%s.html'
Files are contained into sections, depending on how Sami needs to treat them:
* `static`: Files are copied as is (for assets like images, stylesheets, or
JavaScript files);
* `global`: Templates that do not depend on the current class context;
* `namespace`: Templates that should be generated for every namespace;
* `class`: Templates that should be generated for every class.
@@ -0,0 +1,42 @@
<?php
/*
* This file is part of the Sami utility.
*
* (c) Fabien Potencier <fabien@symfony.com>
*
* This source file is subject to the MIT license that is bundled
* with this source code in the file LICENSE.
*/
namespace Sami\Console;
use Symfony\Component\Console\Application as BaseApplication;
use Sami\Console\Command\UpdateCommand;
use Sami\Console\Command\ParseCommand;
use Sami\Console\Command\RenderCommand;
use Sami\Sami;
use Sami\ErrorHandler;
class Application extends BaseApplication
{
/**
* Constructor.
*/
public function __construct()
{
error_reporting(-1);
ErrorHandler::register();
parent::__construct('Sami', Sami::VERSION);
$this->add(new UpdateCommand());
$this->add(new ParseCommand());
$this->add(new RenderCommand());
}
public function getLongVersion()
{
return parent::getLongVersion().' by <comment>Fabien Potencier</comment>';
}
}
Oops, something went wrong.

0 comments on commit aa8d086

Please sign in to comment.