Merge branch 'feature/documentation'

Close #13 Close #14 Fixes #10 Fixes #12
zendframework · Apr 25, 2016 · 1fd1ba8 · 1fd1ba8
2 parents 134afe4 + c7b3d04
commit 1fd1ba8
Show file tree

Hide file tree

Showing 19 changed files with 668 additions and 580 deletions.
diff --git a/.gitignore b/.gitignore
@@ -6,7 +6,9 @@
 .*.sw*
 .*.un~
 nbproject
+doc/html/
 tmp/
+zf-mkdoc-theme/
 
 clover.xml
 composer.lock

diff --git a/.travis.yml b/.travis.yml
@@ -4,16 +4,23 @@ language: php
 
 branches:
   except:
-    - /^release-.*$/
+    - /^release-\d+\.\d+\.\d+.*$/
     - /^ghgfk-.*$/
 
 cache:
   directories:
     - $HOME/.composer/cache
+    - $HOME/.local
+    - zf-mkdoc-theme
 
 env:
   global:
     - CODE_VERSION="^3.0"
+    - SITE_URL: https://zendframework.github.io/zend-di
+    - GH_USER_NAME: "Matthew Weier O'Phinney"
+    - GH_USER_EMAIL: matthew@weierophinney.net
+    - GH_REF: github.com/zendframework/zend-di.git
+    - secure: "nhJ+hLBlGBu5P8udHwGk5eF6mUKubWF5ID+FXHcP86puQzprYIR7Trdv2u4N9M5AKTPKg3Me1QFqR2WgbNyyVWrtyGovCOAFMeZiMBExpNXONoVaAXGlsXCZe6a85Wn54HXeBjuJMKDNlt6LiJqteMf0axyk44h1V/rTbWK5ALKPy2kuILLZgVyEYtwVmrELBduvqR3uHx5PjuGCeJP8LOICuuu7m2JBhWqUBse89vYqhalvXsIButjSrxPmwgSpjOt7zksf//5HwoY1A83+cb6LfR/ZBe1bOgLtfjBBtYyjwL3DsnYPWecfd4qgO69oHT5ZhxOfzLxjSlvtPK0SrH8WEIcFjUnpcGeqyOnydq7HgEC9J6Fnq1VwKLI2VbM/+qQQqvlVDYAQuXvb/YG0sV0x0ad9zEtJ7QPOY8C6ygGm41+lERd39VzQqq5w8IkjXeUAhWzX+ts7w2aIZ3uPYCHoqmvV9DK44/fkmtFHsJU9guDcW1GU/QT91DGVSNMP0qZsZmw6H/kQtDH672GM4xQzv2FgIyqzSY0oggQwtG5y1XkPCr+X2VsSvtTXuihi+ru9g7iqEXU+2aUOyMfB3xnZQ5qiiQUpaatWO/KzRfp/h3b7InPne+nYTrCDfkjJ8N6bypkXv8D6EC/a4zK3XaaMyn0rQ4yPcd99BjHRIOs="
 
 matrix:
   fast_finish: true
@@ -27,6 +34,8 @@ matrix:
     - php: 5.6
       env:
         - EXECUTE_TEST_COVERALLS=true
+        - DEPLOY_DOCS="$(if [[ $TRAVIS_BRANCH == 'master' && $TRAVIS_PULL_REQUEST == 'false' ]]; then echo -n 'true' ; else echo -n 'false' ; fi)"
+        - PATH="$HOME/.local/bin:$PATH"
     - php: 5.6
       env:
         - CODE_VERSION="^2.6"
@@ -58,6 +67,10 @@ script:
   - if [[ $EXECUTE_TEST_COVERALLS == 'true' ]]; then ./vendor/bin/phpunit --coverage-clover clover.xml ; fi
   - if [[ $EXECUTE_TEST_COVERALLS != 'true' ]]; then ./vendor/bin/phpunit ; fi
   - if [[ $EXECUTE_CS_CHECK == 'true' ]]; then ./vendor/bin/php-cs-fixer fix -v --diff --dry-run ; fi
+  - if [[ $DEPLOY_DOCS == "true" && "$TRAVIS_TEST_RESULT" == "0" ]]; then wget -O theme-installer.sh "https://raw.githubusercontent.com/zendframework/zf-mkdoc-theme/master/theme-installer.sh" ; chmod 755 theme-installer.sh ; ./theme-installer.sh ; fi
+
+after_success:
+  - if [[ $DEPLOY_DOCS == "true" ]]; then echo "Preparing to build and deploy documentation" ; ./zf-mkdoc-theme/deploy.sh ; echo "Completed deploying documentation" ; fi
 
 after_script:
   - if [[ $EXECUTE_TEST_COVERALLS == 'true' ]]; then ./vendor/bin/coveralls ; fi
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -2,27 +2,28 @@
 
 All notable changes to this project will be documented in this file, in reverse chronological order by release.
 
-## 2.6.1 - TBD
+## 2.6.1 - 2016-04-25
 
 ### Added
 
-- Nothing.
+- Adds all existing documentation and publishes it at
+  https://zendframework.github.io/zend-di/
 
 ### Deprecated
 
 - Nothing.
 
 ### Removed
 
+- Nothing.
+
+### Fixed
+
 - [#3](https://github.com/zendframework/zend-di/pull/3) fixes how
   `InstanceManager::sharedInstancesWithParams()` behaves when multiple calls are
   made with different sets of parameters (it should return different instances
   in that situation).
 
-### Fixed
-
-- Nothing.
-
 ## 2.6.0 - 2016-02-23
 
 ### Added

diff --git a/README.md b/README.md
@@ -8,6 +8,5 @@ are widely used to create object instances that have all dependencies resolved
 and injected. Dependency Injection containers are one form of IoC – but not the
 only form.
 
-
 - File issues at https://github.com/zendframework/zend-di/issues
-- Documentation is at http://framework.zend.com/manual/current/en/index.html#zend-di
+- Documentation is at https://zendframework.github.io/zend-di/
diff --git a/doc/book/config.md b/doc/book/config.md
@@ -0,0 +1,33 @@
+# Configuration
+
+Most of the configuration for both the setup of `Definition`s as well as the
+setup of the `InstanceManager` can be attained by a configuration file. This
+file will produce an array (typically) and have an iterable structure.
+
+The top two keys are 'definition' and 'instance', each specifying values for
+the definition setup and instance manager setup, respectively.
+
+The definition section expects the following information expressed as a PHP
+array:
+
+```php
+$config = [
+    'definition' => [
+        'compiler' => [/* @todo compiler information */],
+        'runtime'  => [/* @todo runtime information */],
+        'class' => [
+            'instantiator' => '', // the name of the instantiator, by default this is __construct
+            'supertypes'   => [], // an array of supertypes the class implements
+            'methods'      => [
+                'setSomeParameter' => [ // a method name
+                    'parameterName' => [
+                        'name',        // string parameter name
+                        'type',        // type or null
+                        'is-required', // bool
+                    ),
+                ),
+            ),
+        ),
+    ),
+);
+```
diff --git a/...end.di.debugging-and-complex-use-cases.md → doc/book/debugging-and-complex-use-cases.md b/...end.di.debugging-and-complex-use-cases.md → doc/book/debugging-and-complex-use-cases.md
@@ -1,29 +1,31 @@
-# Zend\\Di Debugging & Complex Use Cases
+# Debugging & Complex Use Cases
 
 ## Debugging a DiC
 
-It is possible to dump the information contained within both the Definition and InstanceManager for
-a Di instance.
+It is possible to dump the information contained within both the `Definition`
+and `InstanceManager` for a `Zend\Di\Di` instance.
 
 The easiest way is to do the following:
 
 ```php
 Zend\Di\Display\Console::export($di);
 ```
 
-If you are using a RuntimeDefinition where upon you expect a particular definition to be resolve at
-the first-call, you can see that information to the console display to force it to read that class:
+If you are using a `RuntimeDefinition` where upon you expect a particular
+definition to be resolve at the first-call, you can see that information to the
+console display to force it to read that class:
 
 ```php
-Zend\Di\Display\Console::export($di, array('A\ClassIWantTo\GetTheDefinitionFor'));
+Zend\Di\Display\Console::export($di, ['A\ClassIWantTo\GetTheDefinitionFor']);
 ```
 
 ## Complex Use Cases
 
 ### Interface Injection
 
 ```php
-namespace Foo\Bar {
+namespace Foo\Bar
+{
     class Baz implements BamAwareInterface
     {
         public $bam;
@@ -33,9 +35,11 @@ namespace Foo\Bar {
             $this->bam = $bam;
         }
     }
+
     class Bam
     {
     }
+
     interface BamAwareInterface
     {
         public function setBam(Bam $bam);
@@ -52,7 +56,8 @@ namespace {
 ### Setter Injection with Class Definition
 
 ```php
-namespace Foo\Bar {
+namespace Foo\Bar
+{
     class Baz
     {
         public $bam;
@@ -62,29 +67,31 @@ namespace Foo\Bar {
             $this->bam = $bam;
         }
     }
+
     class Bam {
     }
 }
 
 namespace {
     $di = new Zend\Di\Di;
-    $di->configure(new Zend\Di\Config(array(
-        'definition' => array(
-            'class' => array(
-                'Foo\Bar\Baz' => array(
-                    'setBam' => array('required' => true)
-                )
-            )
-        )
-    )));
+    $di->configure(new Zend\Di\Config([
+        'definition' => [
+            'class' => [
+                'Foo\Bar\Baz' => [
+                    'setBam' => ['required' => true],
+                ],
+            ],
+        ],
+    ]));
     $baz = $di->get('Foo\Bar\Baz');
 }
 ```
 
 ### Multiple Injections To A Single Injection Point
 
 ```php
-namespace Application {
+namespace Application
+{
     class Page
     {
         public $blocks;
@@ -94,6 +101,7 @@ namespace Application {
             $this->blocks[] = $block;
         }
     }
+
     interface Block
     {
     }
@@ -107,25 +115,28 @@ namespace MyModule {
 namespace {
     include 'zf2bootstrap.php';
     $di = new Zend\Di\Di;
-    $di->configure(new Zend\Di\Config(array(
-        'definition' => array(
-            'class' => array(
-                'Application\Page' => array(
-                    'addBlock' => array(
-                        'block' => array('type' => 'Application\Block', 'required' => true)
-                    )
-                )
-            )
-        ),
-        'instance' => array(
-            'Application\Page' => array(
-                'injections' => array(
+    $di->configure(new Zend\Di\Config([
+        'definition' => [
+            'class' => [
+                'Application\Page' => [
+                    'addBlock' => [
+                        'block' => [
+                            'type' => 'Application\Block',
+                            'required' => true
+                        ],
+                    ],
+                ],
+            ],
+        ],
+        'instance' => [
+            'Application\Page' => [
+                'injections' => [
                     'MyModule\BlockOne',
-                    'MyModule\BlockTwo'
-                )
-            )
-        )
-    )));
+                    'MyModule\BlockTwo',
+                ],
+            ],
+        ],
+    ]));
     $page = $di->get('Application\Page');
 }
 ```