Merge pull request #472 from symfony-cmf/odm-doc

cleaning up the odm documentation

Author: dbu

book/database_layer.rst

@@ -14,6 +14,14 @@ In this chapter, you will learn how to work with the Doctrine PHPCR-ODM.
     Read more about choosing the correct storage layer in
     :doc:`../cookbook/database/choosing_storage_layer`
 
+.. note::
+
+    This chapter assumes you are using a Symfony setup with PHPCR-ODM already
+    set up, like the :doc:`CMF Standard Edition <installation>`  or the
+    :doc:`CMF sandbox <../cookbook/editions/cmf_sandbox>`. See
+    :doc:`../bundles/phpcr_odm/introduction` for how to set up PHPCR-ODM in
+    your applications.
+
 PHPCR: A Tree Structure
 -----------------------
 
@@ -34,10 +42,9 @@ Multilanguage support.
 .. sidebar:: PHPCR Implementations
 
     In order to let the Doctrine PHPCR-ODM communicate with the PHPCR, a PHPCR
-    implementation is needed. `Jackalope`_ is the reference PHPCR implementation,
-    which can work with `Apache Jackrabbit`_ (with the `jackalope-jackrabbit`_
-    package) and with Doctrine DBAL (providing support for postgres, sqlite
-    and mysql) with the `jackalope-doctrine-dbal`_ package.
+    implementation is needed. See
+    ":doc:`../cookbook/database/choosing_phpcr_implementation`" for an overview
+    of the available implementations.
 
 A Simple Example: A Task
 ------------------------
@@ -94,30 +101,30 @@ class via annotations:
         // src/Acme/TaskBundle/Document/Task.php
         namespace Acme\TaskBundle\Document;
 
-        use Doctrine\ODM\PHPCR\Mapping\Annotations as PHPCR;
+        use Doctrine\ODM\PHPCR\Mapping\Annotations as PHPCRODM;
 
         /**
-         * @PHPCR\Document()
+         * @PHPCRODM\Document()
          */
         class Task
         {
             /**
-             * @PHPCR\Id()
+             * @PHPCRODM\Id()
              */
             protected $id;
 
             /**
-             * @PHPCR\String()
+             * @PHPCRODM\String()
              */
             protected $description;
 
             /**
-             * @PHPCR\Boolean()
+             * @PHPCRODM\Boolean()
              */
             protected $done = false;
 
             /**
-             * @PHPCR\ParentDocument()
+             * @PHPCRODM\ParentDocument()
              */
             protected $parentDocument;
         }
@@ -168,8 +175,8 @@ After this, you have to create getters and setters for the properties.
     ``Nodename``.
 
     A Document must have an id property. This represents the full path (parent
-    + name) of the Document. This will be set by Doctrine by default and it is
-    not recommend to use the id to determine the location of a Document.
+    path + name) of the Document. This will be set by Doctrine by default and
+    it is not recommend to use the id to determine the location of a Document.
 
     For more information about identifier generation strategies, refer to the
     `doctrine documentation`_
@@ -178,11 +185,11 @@ After this, you have to create getters and setters for the properties.
 
     You can also check out Doctrine's `Basic Mapping Documentation`_ for all
     details about mapping information. If you use annotations, you'll need to
-    prepend all annotations with ``PHPCR\``, which is the name of the imported
-    namespace (e.g. ``PHPCR\Document(..)``), this is not shown in Doctrine's
-    documentation. You'll also need to include the use
-    ``use Doctrine\ODM\PHPCR\Mapping\Annotations as PHPCR;`` statement, which
-    imports the PHPCR annotations prefix.
+    prepend all annotations with ``@PHPCRODM\``, which is the name of the imported
+    namespace (e.g. ``@PHPCRODM\Document(..)``), this is not shown in Doctrine's
+    documentation. You'll also need to include the
+    ``use Doctrine\ODM\PHPCR\Mapping\Annotations as PHPCRODM;`` statement to
+    import the PHPCR annotations prefix.
 
 Persisting Documents to PHPCR
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
@@ -331,14 +338,14 @@ Doctrine, it's already managed.
 Deleting an Object
 ~~~~~~~~~~~~~~~~~~
 
-Deleting an object is very similar, but requires a call to the ``remove()`` method
-of the document manager after you fetched the document from PHPCR::
+Deleting an object is very similar, but requires a call to the ``remove()``
+method of the document manager after you fetched the document from PHPCR::
 
     $documentManager->remove($task);
     $documentManager->flush();
 
-As you might expect, the ``remove()`` method notifies Doctrine that you'd like to
-remove the given document from PHPCR. The actual delete operation
+As you might expect, the ``remove()`` method notifies Doctrine that you'd like
+to remove the given document from PHPCR. The actual delete operation
 however, is not actually executed until the ``flush()`` method is called.
 
 Summary
@@ -351,19 +358,16 @@ mapping metadata information to map an object's data to a particular database
 table.
 
 And even though Doctrine revolves around a simple concept, it's incredibly
-powerful, allowing you to create complex queries and subscribe to events that
-allow you to take different actions as objects go through their persistence
-lifecycle.
+powerful, allowing you to `create complex queries`_ and
+:doc:`subscribe to events <../bundles/phpcr_odm/events>` that allow you to
+take different actions as objects go through their persistence lifecycle.
 
 .. _`Doctrine PHPCR-ODM`: http://docs.doctrine-project.org/projects/doctrine-phpcr-odm/en/latest/index.html
 .. _`PHP Content Repository`: http://phpcr.github.io/
 .. _`JSR-283 specification`: http://jcp.org/en/jsr/detail?id=283
 .. _`Doctrine ORM`: http://symfony.com/doc/current/book/doctrine.html
-.. _`Jackalope`: http://jackalope.github.io/
-.. _`Apache Jackrabbit`: http://jackrabbit.apache.org/
-.. _`jackalope-jackrabbit`: https://github.com/jackalope/jackalope-jackrabbit
-.. _`jackalope-doctrine-dbal`: https://github.com/jackalope/jackalope-doctrine-dbal
 .. _`doctrine documentation`: http://docs.doctrine-project.org/projects/doctrine-phpcr-odm/en/latest/reference/basic-mapping.html#basicmapping-identifier-generation-strategies
 .. _`Basic Mapping Documentation`: http://docs.doctrine-project.org/projects/doctrine-phpcr-odm/en/latest/reference/annotations-reference.html
 .. _`the QueryBuilder documentation`: http://docs.doctrine-project.org/projects/doctrine-phpcr-odm/en/latest/reference/query-builder.html
+.. _`create complex queries`: http://docs.doctrine-project.org/projects/doctrine-phpcr-odm/en/latest/reference/query-builder.html
 .. _`Custom Repository Classes`: http://symfony.com/doc/current/book/doctrine.html#custom-repository-classes

book/installation.rst

@@ -39,7 +39,7 @@ storage medium.
     can use one of several available data storage mechanisms without having to
     rewrite your code. For more information on the different available
     mechanisms and how to install and configure them, refer to
-    :doc:`../cookbook/installing_configuring_doctrine_phpcr_odm`
+    :doc:`../bundles/phpcr_odm/introduction`.
 
 Installation
 ------------
@@ -221,7 +221,7 @@ into the PHPCR database by calling:
 
 .. code-block:: bash
 
-    $ php app/console doctrine:phpcr:migrator page --identifier=/cms/simple/test
+    $ php app/console doctrine:phpcr:migrator:migrate page --identifier=/cms/simple/test
 
 Note that the above identifier is mapped to
 ``app/Resources/data/pages/test.yml`` by stripping off the ``basepath``
@@ -233,7 +233,7 @@ and then run the following command:
 
 .. code-block:: bash
 
-    $ php app/console doctrine:phpcr:migrator page --identifier=/cms/simple/test/foo
+    $ php app/console doctrine:phpcr:migrator:migrate page --identifier=/cms/simple/test/foo
 
 .. _`cmf.liip.ch`: http://cmf.liip.ch
 .. _`Requirements for running Symfony2`: http://symfony.com/doc/current/reference/requirements.html

bundles/blog.rst

@@ -37,7 +37,7 @@ Dependencies
 
 * :doc:`CmfRoutingBundle <routing/introduction>` is used to manage the routing;
 * :doc:`CmfRoutingAutoBundle <routing_auto/introduction>` is used to manage automatically generate routes;
-* :doc:`PHPCR-ODM <phpcr_odm>` is used to persist the bundles documents.
+* :doc:`PHPCR-ODM <phpcr_odm/introduction>` is used to persist the bundles documents.
 
 Configuration
 -------------

bundles/index.rst

@@ -9,7 +9,7 @@ Bundles
     content/index
     core/index
     create/index
-    phpcr_odm
+    phpcr_odm/index
     media/index
     menu/index
     routing_auto/index

bundles/map.rst.inc

@@ -92,9 +92,14 @@ Contributed Bundles
 Besides that, the Symfony CMF team also maintains some 3th party bundles which
 help with integrating PHPCR concepts into the Symfony Framework.
 
-* **DoctrinePHPCRBundle**
-
-  * :doc:`phpcr_odm`
+* :doc:`phpcr_odm/index`
+
+  * :doc:`phpcr_odm/introduction`
+  * :doc:`phpcr_odm/events`
+  * :doc:`phpcr_odm/forms`
+  * :doc:`phpcr_odm/fixtures_initializers`
+  * :doc:`phpcr_odm/multilang`
+  * :doc:`phpcr_odm/multiple_sessions`
 
 * SonataDoctrinePHPCRAdminBundle_