Merge pull request #6 from baleen/docs-reference

sphpdox

composer.json

@@ -30,6 +30,7 @@
 		"squizlabs/php_codesniffer": "2.*",
 		"phploc/phploc": "^2.1",
 		"phpmd/phpmd": "^2.2",
-		"sebastian/phpcpd": "^2.0"
+		"sebastian/phpcpd": "^2.0",
+        "sphpdox/sphpdox": "dev-master"
     }
 }

docs/bin/generate-docs.sh → docs/bin/build-docs.sh

@@ -3,5 +3,5 @@ EXECPATH=`dirname $0`
 cd $EXECPATH
 cd ..
 
-rm build -Rf
+#rm -rf build
 sphinx-build -b html en build/html

docs/bin/generate-reference.sh

@@ -0,0 +1,9 @@
+#!/bin/bash
+EXECPATH=`dirname $0`
+cd $EXECPATH
+cd ..
+
+rm -rf en/ref/Baleen
+mkdir -p en/ref/Baleen
+../vendor/bin/sphpdox process -o en/ref Baleen\\Migrations ../lib
+find en/ref -name "*.rst" -exec bash -c 'mv "$1" "$(sed "s/\.rst$/.txt/" <<< "$1")"' - '{}' \;

docs/en/conf.py

@@ -1,6 +1,6 @@
 # -*- coding: utf-8 -*-
 #
-# Baleen documentation build configuration file, created by
+# Baleen Migrations documentation build configuration file, created by
 # sphinx-quickstart on Fri Jul 10 17:10:31 2015.
 #
 # This file is execfile()d with the current directory set to its
@@ -31,9 +31,13 @@
 # Add any Sphinx extension module names here, as strings. They can be
 # extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
 # ones.
-extensions = [
-    'sphinx.ext.todo',
-]
+extensions = ['sphinxcontrib.phpdomain']
+
+# The name of the default domain.
+primary_domain = 'php'
+
+# The default language to highlight source code in.
+highlight_language = 'php'
 
 # Add any paths that contain templates here, relative to this directory.
 templates_path = ['_templates']
@@ -50,7 +54,7 @@
 master_doc = 'index'
 
 # General information about the project.
-project = u'Baleen'
+project = u'Baleen Migrations'
 copyright = u'2015, Gabriel Somoza <gabriel@strategery.io>, Mike Simonson <contact@mikesimonson.com>'
 author = u'Gabriel Somoza <gabriel@strategery.io>, Mike Simonson <contact@mikesimonson.com>'
 
@@ -59,9 +63,9 @@
 # built documents.
 #
 # The short X.Y version.
-version = '0.2'
+version = '0.7'
 # The full version, including alpha/beta/rc tags.
-release = '0.2.1'
+release = '0.7.0'
 
 # The language for content autogenerated by Sphinx. Refer to documentation
 # for a list of supported languages.
@@ -105,7 +109,7 @@
 #keep_warnings = False
 
 # If true, `todo` and `todoList` produce output, else they produce nothing.
-todo_include_todos = True
+todo_include_todos = False
 
 
 # -- Options for HTML output ----------------------------------------------
@@ -204,7 +208,7 @@
 #html_search_scorer = 'scorer.js'
 
 # Output file base name for HTML help builder.
-htmlhelp_basename = 'Baleendoc'
+htmlhelp_basename = 'BaleenMigrationsdoc'
 
 # -- Options for LaTeX output ---------------------------------------------
 
@@ -226,8 +230,8 @@
 # (source start file, target name, title,
 #  author, documentclass [howto, manual, or own class]).
 latex_documents = [
-  (master_doc, 'Baleen.tex', u'Baleen Documentation',
-   u'Gabriel Somoza \\textless{}gabriel@strategery.io\\textgreater{}, Mike Simonson \\textless{}contact@mikesimonson.com\\textgreater{}', 'manual'),
+  (master_doc, 'BaleenMigrations.tex', u'Baleen Migrations Documentation',
+   u'Gabriel Somoza \\textless{}gabriel@strategery.io\\textgreater{}', 'manual'),
 ]
 
 # The name of an image file (relative to this directory) to place at the top of
@@ -256,7 +260,7 @@
 # One entry per manual page. List of tuples
 # (source start file, name, description, authors, manual section).
 man_pages = [
-    (master_doc, 'baleen', u'Baleen Documentation',
+    (master_doc, 'baleenmigrations', u'Baleen Migrations Documentation',
      [author], 1)
 ]
 
@@ -270,8 +274,8 @@
 # (source start file, target name, title, author,
 #  dir menu entry, description, category)
 texinfo_documents = [
-  (master_doc, 'Baleen', u'Baleen Documentation',
-   author, 'Baleen', 'One line description of project.',
+  (master_doc, 'BaleenMigrations', u'Baleen Migrations Documentation',
+   author, 'BaleenMigrations', 'One line description of project.',
    'Miscellaneous'),
 ]
 

docs/en/domain-model.txt

@@ -0,0 +1,8 @@
+Domain Model
+============
+
+.. toctree::
+   :glob:
+   :maxdepth: 2
+
+   domain-model/*

docs/en/glossary.txt → docs/en/domain-model/glossary.txt

@@ -62,14 +62,3 @@ as to provide information about the different models that make up the "migration
    Version Collection
       A special object to represent and sort a set of Collection. Its important to note that it behaves as an ordered
       set of elements.
-
-Core Models
------------
-
-.. toctree::
-   :maxdepth: 2
-
-   core-concepts/migration
-   core-concepts/timeline
-
-

docs/en/examples/simple-usage.txt

@@ -42,4 +42,4 @@ The following example illustrates how you can use Baleen migrations from within
        method. You can also pass RunOptions to most of the other Timeline methods. */
 
 
-To see how you can put migration files into the `./migrations` directory refer to :doc:`sample-migrations`.
+.. To see how you can put migration files into the `./migrations` directory refer to the :doc:`examples`.

docs/en/index.txt

@@ -1,12 +1,12 @@
 Baleen Migrations
 =================
 
-Baleen Migrations is a project that seeks to abstract the domain logic of performing migrations of any kind into a
-single package. Its simple goal is to excel at one single task: provide an intuitive, well-tested framework to migrate
-from point A to point B (or vice-versa if going down).
+Baleen Migrations is a project that seeks to abstract the domain of performing migrations of any kind into a single
+independent package. Its goal is to excel at one single task: provide an intuitive, well-tested framework to migrate
+"something" from point A to point B (or vice-versa if going down).
 
-In other words, we take care of WHICH migrations are run and in what ORDER. Everything else is left up to the
-implementation:
+In other words, we take care of WHICH migrations are run and the mechanism to run them. Everything else is the
+responsibility of the implementation:
 
 * WHAT is going to be migrated? It could be a database, images, documents, etc.
 * HOW its going to be migrated? You can wrap each migration into DB transactions. Or not, its up to you.
@@ -20,10 +20,10 @@ Contents:
    :maxdepth: 2
 
    getting-started
-   migration
-   timeline
+   domain-model
+   examples
    implementations
-   glossary
+   reference
 
 Indices and Tables
 ==================

docs/en/ref/Baleen/Migrations/Event/CanDispatchEventsTrait.txt

@@ -0,0 +1,31 @@
+-------------------------------------------------
+Baleen\\Migrations\\Event\\CanDispatchEventsTrait
+-------------------------------------------------
+
+.. php:namespace: Baleen\\Migrations\\Event
+
+.. php:trait:: CanDispatchEventsTrait
+
+    Allows classes to OPTIONALLY receive an EventDispatcher to dispatch events. Making it optional puts responsibility
+    on the implementation: if the EventDispatcher is not available then no events are dispatched.
+
+    .. php:attr:: eventDispatcher
+
+        protected null|EventDispatcherInterface
+
+    .. php:method:: getEventDispatcher()
+
+        :returns: null|EventDispatcherInterface
+
+    .. php:method:: setEventDispatcher(EventDispatcherInterface $eventDispatcher)
+
+        :type $eventDispatcher: EventDispatcherInterface
+        :param $eventDispatcher:
+
+    .. php:method:: dispatchEvent($name, Event $event)
+
+        Dispatches an event if an EventDispatcher is available.
+
+        :param $name:
+        :type $event: Event
+        :param $event:

docs/en/ref/Baleen/Migrations/Event/EmitterInterface.txt

@@ -0,0 +1,18 @@
+-------------------------------------------
+Baleen\\Migrations\\Event\\EmitterInterface
+-------------------------------------------
+
+.. php:namespace: Baleen\\Migrations\\Event
+
+.. php:interface:: EmitterInterface
+
+    Interface EmitterInterface.
+
+    .. php:method:: setEventDispatcher(EventDispatcherInterface $eventDispatcher)
+
+        :type $eventDispatcher: EventDispatcherInterface
+        :param $eventDispatcher:
+
+    .. php:method:: getEventDispatcher()
+
+        :returns: EventDispatcherInterface

docs/en/ref/Baleen/Migrations/Event/EventInterface.txt

@@ -0,0 +1,9 @@
+-----------------------------------------
+Baleen\\Migrations\\Event\\EventInterface
+-----------------------------------------
+
+.. php:namespace: Baleen\\Migrations\\Event
+
+.. php:interface:: EventInterface
+
+    Interface MigrationsEvent.

docs/en/ref/Baleen/Migrations/Event/HasEmitterTrait.txt

@@ -0,0 +1,47 @@
+------------------------------------------
+Baleen\\Migrations\\Event\\HasEmitterTrait
+------------------------------------------
+
+.. php:namespace: Baleen\\Migrations\\Event
+
+.. php:trait:: HasEmitterTrait
+
+    Trait to be used by classes that fire events through a specialised emitter. For example, the Timeline
+    class will use this trait to fire events using the TimelineEmitter.
+
+    .. php:attr:: emitter
+
+        protected EmitterInterface
+
+    .. php:method:: setEventDispatcher(EventDispatcherInterface $eventDispatcher)
+
+        Set the EventDispatcher for the emitter. This is public to allow attaching
+        a previously existing EventDispatcher.
+
+        :type $eventDispatcher: EventDispatcherInterface
+        :param $eventDispatcher:
+
+    .. php:method:: getEmitter()
+
+        Returns the emitter for the class. Creates one if necessary.
+
+        :returns: EmitterInterface
+
+    .. php:method:: setEmitter(EmitterInterface $emitter)
+
+        Sets the emitter for the class.
+
+        :type $emitter: EmitterInterface
+        :param $emitter:
+
+    .. php:method:: createEmitter()
+
+        Must create and return a default emitter.
+
+        :returns: EmitterInterface
+
+    .. php:method:: getEventDispatcher()
+
+        Get the event dispatcher from the emitter.
+
+        :returns: EventDispatcherInterface

docs/en/ref/Baleen/Migrations/Event/Timeline/CollectionEvent.txt

@@ -0,0 +1,54 @@
+----------------------------------------------------
+Baleen\\Migrations\\Event\\Timeline\\CollectionEvent
+----------------------------------------------------
+
+.. php:namespace: Baleen\\Migrations\\Event\\Timeline
+
+.. php:class:: CollectionEvent
+
+    Class CollectionEvent.
+
+    .. php:attr:: collection
+
+        protected LinkedVersions
+
+    .. php:attr:: options
+
+        protected Options
+
+    .. php:attr:: target
+
+        protected Version
+
+    .. php:attr:: progress
+
+        protected Progress
+
+    .. php:method:: __construct(Version $target, Options $options, LinkedVersions $versions, Progress $progress = null)
+
+        CollectionEvent constructor.
+
+        :type $target: Version
+        :param $target:
+        :type $options: Options
+        :param $options:
+        :type $versions: LinkedVersions
+        :param $versions:
+        :type $progress: Progress
+        :param $progress:
+
+    .. php:method:: getOptions()
+
+        :returns: Options
+
+    .. php:method:: getCollection()
+
+        :returns: LinkedVersions
+
+    .. php:method:: getTarget()
+
+        :returns: Version
+
+    .. php:method:: getProgress()
+
+        :returns: Progress

docs/en/ref/Baleen/Migrations/Event/Timeline/MigrationEvent.txt

@@ -0,0 +1,44 @@
+---------------------------------------------------
+Baleen\\Migrations\\Event\\Timeline\\MigrationEvent
+---------------------------------------------------
+
+.. php:namespace: Baleen\\Migrations\\Event\\Timeline
+
+.. php:class:: MigrationEvent
+
+    Class MigrationEvent.
+
+    .. php:attr:: options
+
+        protected Options
+
+    .. php:attr:: version
+
+        protected Version
+
+    .. php:attr:: progress
+
+        protected Progress
+
+    .. php:method:: __construct(Version $version, Options $options, Progress $progress = null)
+
+        MigrationEvent constructor.
+
+        :type $version: Version
+        :param $version:
+        :type $options: Options
+        :param $options:
+        :type $progress: Progress
+        :param $progress:
+
+    .. php:method:: getOptions()
+
+        :returns: Options
+
+    .. php:method:: getVersion()
+
+        :returns: Version
+
+    .. php:method:: getProgress()
+
+        :returns: Progress