Merge pull request #457 from liip/doc-improvements

Doc improvements

Resources/doc/index.rst

@@ -3,17 +3,17 @@
    You can adapt this file completely to your liking, but it should at least
    contain the root `toctree` directive.
 
-Welcome to Sonata - Doctrine ORM Admin's documentation!
-=======================================================
+Welcome to Sonata - Admin's documentation!
+==========================================
 
-The ``Doctrine ORM Admin`` provides services to work with the ``Admin Bundle`` and the ``Doctrine Project``.
+SonataAdminBundle - The missing Symfony2 Admin Generator
 
 **Warning**: The bundle has been split into 4 bundles :
 
 * SonataAdminBundle : the current one, contains core librairies and services
-* `SonataDoctrineORMAdminBundle <https://github.com/sonata-project/SonataDoctrineORMAdminBundle>`_: Integrates the admin bundle into with the Doctrine ORM project
-* `SonataDoctrineMongoDBAdminBundle <https://github.com/sonata-project/SonataDoctrineMongoDBAdminBundle>`_: Integrates the admin bundle into with MongoDB (early stage)
-* `SonataDoctrinePhpcrAdminBundle <https://github.com/sonata-project/SonataDoctrinePhpcrAdminBundle>`_: Integrates the admin bundle into with PHPCR (early stage)
+* `SonataDoctrineORMAdminBundle <https://github.com/sonata-project/SonataDoctrineORMAdminBundle>`_: Integrates the admin bundle with the Doctrine ORM project
+* `SonataDoctrineMongoDBAdminBundle <https://github.com/sonata-project/SonataDoctrineMongoDBAdminBundle>`_: Integrates the admin bundle with MongoDB (early stage)
+* `SonataDoctrinePhpcrAdminBundle <https://github.com/sonata-project/SonataDoctrinePhpcrAdminBundle>`_: Integrates the admin bundle with PHPCR (early stage)
 
 **Google Groups**: For questions and proposals you can post on this google groups
 

Resources/doc/reference/configuration.rst

@@ -19,7 +19,7 @@ Full Configuration Options
 .. code-block:: yaml
 
     sonata_admin:
-       security_handler: sonata.admin.security.handler.noop
+        security_handler: sonata.admin.security.handler.noop
 
         title:      Sonata Project
         title_logo: /bundles/sonataadmin/logo_title.png

Resources/doc/reference/security.rst

@@ -11,6 +11,7 @@ you can set the ``security_handler`` to ``sonata.admin.security.handler.acl``.
 
 .. code-block:: yaml
 
+    # app/config/config.yml
     sonata_admin:
         security_handler: sonata.admin.security.handler.acl
 
@@ -33,12 +34,55 @@ The security integration is a work in progress and have some knows issues :
 Configuration
 ~~~~~~~~~~~~~
 
-    - The following configuration defines :
+Before you can use ``FriendsOfSymfony/FOSUserBundle`` you need to set it up as described in the documentation
+of the bundle. In step 4 you need to create a User class (in a custom UserBundle). Do it as follows:
 
-        - the ``FriendsOfSymfony/FOSUserBundle`` as a security provider
-        - the login form for authentification
-        - the access control : resources with related required roles, the important part is the admin configuration
-        - the ``acl`` option enable the ACL.
+.. code-block:: php
+
+    <?php
+
+    namespace Acme\UserBundle\Entity;
+
+    use Sonata\UserBundle\Entity\BaseUser as BaseUser;
+    use Doctrine\ORM\Mapping as ORM;
+
+    /**
+     * @ORM\Entity
+     * @ORM\Table(name="fos_user")
+    \*/
+    class User extends BaseUser
+    {
+        /**
+         * @ORM\Id
+         * @ORM\Column(type="integer")
+         * @ORM\GeneratedValue(strategy="AUTO")
+         \*/
+        protected $id;
+
+        public function __construct()
+        {
+            parent::__construct();
+            // your own logic
+        }
+    }
+
+In your ``app/config/config.yml`` you then need to put the following:
+
+.. code-block:: yaml
+
+    fos_user:
+        db_driver: orm
+        firewall_name: main
+        user_class: Acme\UserBundle\Entity\User
+
+The following configuration for the SonataUserBundle defines:
+
+    - the ``FriendsOfSymfony/FOSUserBundle`` as a security provider
+    - the login form for authentification
+    - the access control : resources with related required roles, the important part is the admin configuration
+    - the ``acl`` option enable the ACL.
+
+In ``app/config/config.yml``:
 
 .. code-block:: yaml
 
@@ -46,6 +90,10 @@ Configuration
         # ... other parameters
         security.acl.permission.map.class: Sonata\AdminBundle\Security\Acl\Permission\AdminPermissionMap
 
+In ``app/config/security.yml``:
+
+.. code-block:: yaml
+
     security:
         providers:
             fos_userbundle:
@@ -104,20 +152,12 @@ Configuration
 
 .. code-block::
 
-    # php app/console fos:user:create
+    # php app/console fos:user:create --super-admin
     Please choose a username:root
     Please choose an email:root@domain.com
     Please choose a password:root
     Created user root
 
-
-- Promote an user as super admin :
-
-.. code-block::
-
-    # php app/console fos:user:promote root
-    User "root" has been promoted as a super administrator.
-
 If you have Admin classes, you can install the related CRUD ACL rules :
 
 .. code-block::
@@ -138,4 +178,4 @@ Usage
 ~~~~~
 
 Everytime you create a new ``Admin`` class, you should create start the command ``php app/console sonata:admin:setup-acl``
-so the ACL database will be updated with the latest masks and roles informations.
+so the ACL database will be updated with the latest masks and roles informations.