Assets management documentation (#55)

Makefile

@@ -2,7 +2,7 @@
 #
 # It's auto-generated by sonata-project/dev-kit package.
 
-.PHONY: test docs
+.PHONY: test docs assets
 
 all:
 	@echo "Please choose a task."
@@ -20,3 +20,7 @@ test:
 
 docs:
 	cd Resources/doc && sphinx-build -W -b html -d _build/doctrees . _build/html
+
+assets:
+	cd Resources/assets_src && npm install
+	cd Resources/assets_src && gulp

Resources/doc/index.rst

@@ -10,3 +10,4 @@ Reference Guide
 
    reference/introduction
    reference/installation
+   reference/assets

Resources/doc/reference/assets.rst

@@ -0,0 +1,23 @@
+Assets
+======
+
+Assets are managed with gulp which requires nodejs/npm and a global gulp install.
+
+* stylesheets are generated from .scss files located in ``/Resources/assets_src/src/scss``
+* javascripts are generated from files located in ``/Resources/assets_src/src/js``
+
+.. warning::
+
+   Do not edit directly files located in the ``/Resources/public`` folder,
+   if you want to contribute, you should edit files in the ``/Resources/assets_src/src`` folder.
+
+
+Compiling Sources
+-----------------
+
+If you made some modifications in the sources,
+you can generate the public ones with the following command:
+
+.. code-block:: bash
+
+   make assets

Resources/doc/reference/introduction.rst

@@ -7,6 +7,28 @@ This small introduction will try to explain the basics concepts behind the
 A Dashboard
 -----------
 
+A ``Dashboard`` is a collection of blocks, actually of block containers, containing the
+blocks required to manage its content.
 
 A Block
 -------
+
+The ``SonataDashboardBundle`` does not know how to manage content, actually there is
+no content management. This part is delegated to services. The bundle only
+manages references to the service required by a dashboard. Reference information is
+stored in a ``Block``.
+
+A block is a small unit, it contains the following information:
+
+ - service id
+ - position
+ - settings used by the service
+
+Each block service must implement the ``Sonata\PageBundle\Block\BlockServiceInterface``
+which defines a set of functions to create so the service can be integrated
+nicely with editing workflow. The important information is that a block service
+must always return a ``Response`` object.
+
+By default the ``SonataDashboardBundle`` is shipped with a core block service:
+
+ - sonata.dashboard.block.container      : Block container