Merge pull request #869 from doctrine/add-more-doc

add some more documentation from cmf docs

docs/en/cookbook/choosing-phpcr-implementation.rst

@@ -0,0 +1,40 @@
+.. index::
+    single: PHPCR Implementations
+
+Choosing a PHPCR Implementation
+===============================
+
+To use PHPCR-ODM, you need to decide on the PHPCR implementation you want to
+use. The implementation is a special kind of database that is responsible for
+storing all the content you want to persist. While every content repository
+can have very different requirements and performance characteristics, the API
+is the same for all of them.
+
+Furthermore, since the API defines an export/import format, you can always
+switch to a different content repository implementation later on.
+
+.. tip::
+
+    If you are just getting started with the CMF, it is best to choose a
+    content repository based on a storage engine that you are already familiar
+    with. For example, **Jackalope with Doctrine DBAL** will work with your
+    existing RDBMS and does not require you to install Java Once you have a
+    working application it should be easy to switch to another option.
+
+Jackalope with Jackrabbit
+-------------------------
+
+The most feature complete and performant implementation available today.
+Jackrabbit can persist into the file system, a database and other storage
+layers.
+
+The main drawback is that Jackrabbit requires the Java runtime.
+
+See :doc:`running-jackrabbit` for instructions how to install and run jackrabbit.
+
+Jackalope with Doctrine DBAL
+----------------------------
+
+A solid and tested implementation that is fine for small to medium sized
+projects. It can run on just a relational database (currently tested with
+MySQL, PostgreSQL and SQLite).

docs/en/cookbook/running-jackrabbit.rst

@@ -0,0 +1,36 @@
+.. index::
+    single: Jackrabbit
+
+Running Jackrabbit
+==================
+
+`Apache Jackrabbit`_ is the reference implementation for the Java Content
+Repository (JCR) standard. `jackalope-jackrabbit`_ implements PHPCR on top
+of the Jackrabbit remoting capabilities.
+
+Get the latest Apache Jackrabbit version from the project's
+`official download page`_. Place it in a folder where you want it
+to create the repository fields and start is with:
+
+.. code-block:: bash
+
+    $ java -jar jackrabbit-standalone-*.jar
+
+By default the server is listening on the 8080 port, you can change this
+by specifying the port on the command line:
+
+.. code-block:: bash
+
+    $ java -jar jackrabbit-standalone-*.jar --port 8888
+
+For unix systems, you can get the start-stop script for ``/etc/init.d``
+`here`_.
+
+More information about `running a Jackrabbit server`_ can be found on the
+Jackalope wiki.
+
+.. _`Apache Jackrabbit`: http://jackrabbit.apache.org/jcr/index.html
+.. _`jackalope-jackrabbit`: https://github.com/jackalope/jackalope-jackrabbit
+.. _`official download page`: http://jackrabbit.apache.org/jcr/downloads.html
+.. _`here`: https://github.com/sixty-nine/Jackrabbit-startup-script
+.. _`running a Jackrabbit server`: https://github.com/jackalope/jackalope/wiki/Running-a-jackrabbit-server

docs/en/index.rst

@@ -77,14 +77,11 @@ Cookbook
 --------
 
 * **Tricks**:
+  :doc:`Chosing a PHPCR implementation <cookbook/choosing-phpcr-implementation>` |
+  :doc:`Running Jackrabbit <cookbook/running-jackrabbit>` |
   :doc:`Last modification timestamp <cookbook/last-modified>` |
   :doc:`Custom Document Class Mapper <cookbook/custom_documentclass_mapper>` |
   :doc:`Convert documents between translated and untranslated <cookbook/refactoring-multilang>`
 
-.. TODO: write these
-  |
-  :doc:`Blending ORM and PHPCR-ODM <cookbook/blending-orm-and-phpcr-odm>` |
-  :doc:`Mapping classes to ORM and PHPCR-ODM <cookbook/mapping-classes-to-orm-and-phpcr-odm>` |
-
-Also have a look at the `Doctrine ORM cookbook <http://docs.doctrine-project.org/projects/doctrine-orm/en/latest/#cookbook>`_,
+Also have a look at the `Doctrine ORM cookbook <https://www.doctrine-project.org/projects/doctrine-orm/en/latest/#cookbook>`_,
 notably the entries in the *Implementation* section apply to PHPCR-ODM as well.

docs/en/reference/introduction.rst

@@ -27,9 +27,7 @@ abstract base class or interface. A document class must not be final
 or contain final methods. Additionally it must not implement
 **clone** nor **wakeup**.
 
-.. todo: or :doc:`do so safely <../cookbook/implementing-wakeup-or-clone>`.
-
-See the :doc:`architecture chapter <../reference/architecture>` for a full list of the restrictions
+See the :doc:`architecture chapter <architecture>` for a full list of the restrictions
 that your entities need to comply with.
 
 A document contains persistable properties. A persistable property
@@ -54,29 +52,13 @@ We do not build a web interface but simple run scripts on the command line to ke
 Setup Project
 -------------
 
-Create a file composer.json in your project directory.
-
-.. code-block:: javascript
-
-    {
-        "minimum-stability": "dev",
-        "require": {
-            "doctrine/phpcr-odm": "~1.2",
-            "jackalope/jackalope-doctrine-dbal": "~1.1"
-        },
-        "autoload": {
-          "psr-0": { "Demo\\": "src/" }
-        }
-    }
-
-Then run the following commands on your command line
+Use composer to install PHPCR-ODM and a PHPCR implementation:
 
 .. code-block:: bash
 
-    $ curl -s http://getcomposer.org/installer | php --
-    $ php composer.phar install
+    composer require doctrine/phpcr-odm jackalope/jackalope-doctrine-dbal
 
-This will download the dependencies into the vendor/ folder and generate ``vendor/autoload.php``.
+See :doc:`../cookbook/choosing-phpcr-implementation` for alternatives to the Jackalope Doctrine-DBAL implementation.
 
 .. _intro-bootstrap: