update docs

docs/conf.py

@@ -55,9 +55,9 @@
 # built documents.
 #
 # The short X.Y version.
-version = '3.0.0'
+version = '4.0.0'
 # The full version, including alpha/beta/rc tags.
-release = '3.0.0'
+release = '4.0.0'
 
 # The language for content autogenerated by Sphinx. Refer to documentation
 # for a list of supported languages.
@@ -267,7 +267,7 @@
 #  dir menu entry, description, category)
 texinfo_documents = [
   (master_doc, 'Comodojodispatcher', u'Comodojo dispatcher Documentation',
-   author, 'Comodojodispatcher', 'One line description of project.',
+   author, 'Comodojodispatcher', 'Hackable REST microframework',
    'Miscellaneous'),
 ]
 

docs/configuration.rst

@@ -1,21 +1,136 @@
 Configuration
 =============
 
-.. _dispatcher: https://github.com/comodojo/dispatcher
-.. _dispatcher-installer: https://github.com/comodojo/dispatcher-installer
-.. _dispatcher.framework: https://github.com/comodojo/dispatcher.framework
-.. _psr-3: http://www.php-fig.org/psr/psr-3/
-.. _HTTP/1.1 methods: https://tools.ietf.org/html/rfc2616#section-9
-.. _patch method: https://tools.ietf.org/html/rfc5789
+.. _comodojo/dispatcher: https://github.com/comodojo/dispatcher
 
-The framework can be configured passing the configuration directives as an associative array when creating a new ``\Comodojo\Dispatcher\Dispatcher`` instance.
+The dispatcher framework can be configured passing configuration statements as an associative array when creating a new ``\Comodojo\Dispatcher\Dispatcher`` instance.
+
+.. code-block:: php
+    :linenos:
+
+    use \Comodojo\Dispatcher\Dispatcher;
+    $dispatcher = new \Comodojo\Dispatcher\Dispatcher([
+        // configuration parameters here!
+    ]);
+
+A init time, the configuration is used to create basic objects (e.g. models, cache provider) and can be changed at any time accessing the configuration object (that will be an instance of `\Comodojo\Foundation\Basic\Configuration <https://github.com/comodojo/foundation/blob/master/src/Comodojo/Foundation/Basic/Configuration.php>`_ class).
+
+.. code-block:: php
+    :linenos:
+
+    // get the configuration object
+    $configuration = $dispatcher->getConfiguration();
+
+    // get the base-path value from actual configuration
+    $base_path = $configuration->get('base-path');
+
+    // set the my-param configuration item using standard notation
+    $configuration->set('my-param', 'foo');
+
+    // set the my->remote->url nested configuration item using dot notation
+    $configuration->set('my.remote.url', 'https://example.com')
+
+.. note:: For more information about the ``\Comodojo\Foundation\Base\Configuration`` class, see the `comodojo/foundation documentation <https://docs.comodojo.org/projects/foundation/en/latest/base.html>`_
 
 Configuration parameters
 ------------------------
 
-TBW
+Following the list of configuration statement currently supported by the framework.
+
+.. topic:: (bool) enabled [default: true]
+
+    Enable or disable the framework (i.e. if not enabled, dispatcher cannot serve any request).
+
+.. topic:: (int) disabled-status [default: 503]
+
+    In case not enabled, the HTTP status to return to clients.
+
+.. topic:: (string) disabled-message [default: Dispatcher offline]
+
+    In case not enabled, the HTTP body to return to clients.
+
+.. topic:: (string) encoding [default: UTF-8]
+
+    Active char encoding.
+
+.. topic:: (bool) routing-table-cache [default: true]
+
+    Enable or disable the caching of the routing table.
+
+.. topic:: (int) routing-table-ttl [default: 86400]
+
+    The ttl for the routing table cache.
+
+.. topic:: (array) supported-http-methods (default: null)
+
+    This setting could be used to restring (or enhance) the support for HTTP methods.
+
+    If not defined, the framework will allow the following http verbs:
+
+    - GET
+    - PUT
+    - POST
+    - DELETE
+    - OPTIONS
+    - HEAD
+    - TRACE
+    - CONNECT
+    - PURGE
+
+.. topic:: (array) log
+
+    Logger configuration, input for the ``LogManager::createFromConfiguration()`` method (for more information, see the `comodojo/foundation <https://docs.comodojo.org/projects/foundation/en/latest/logging.html>`_ documentation)
+
+    An example schema:
+
+    .. code-block:: yaml
+        :linenos:
+
+        log:
+            enable: true
+            name: dispatcher
+            providers:
+                local:
+                    type: StreamHandler
+                    level: debug
+                    stream: logs/dispatcher.log
+
+.. topic:: (array) cache
+
+    Cache manager of provider configuration, input for the ``SimpleCacheManager::createFromConfiguration()`` method (for more information, see the `comodojo/cache <https://docs.comodojo.org/projects/cache/en/latest/index.html>`_ documentation)
+
+    An example schema:
+
+    .. code-block:: yaml
+        :linenos:
+
+        cache:
+            enable: true
+            pick_mode: PICK_FIRST
+            providers:
+                local:
+                    type: Filesystem
+                    cache_folder: cache
 
 Automatic configuration parameters
 ----------------------------------
 
-TBW
+The following (basic) configuration parameters are computed and included in the configuration at init time.
+
+.. note:: The user configuration has precedence over the automatic one: if one automatic parameter is included in the user configuration, its value will overwrite the automatic one.
+
+.. topic:: (string) base-path
+
+    The base path of the project directory (i.e. the root of the *vendor* folder).
+
+.. topic:: (string) base-url
+
+    The current URL used to contact the framework.
+
+.. topic:: (string) base-uri
+
+    The full URI used to contact the framework.
+
+.. topic:: (string) base-location
+
+    The relative path before the entry point (i.e. the *index.php* file).

docs/installation.rst

@@ -1,3 +1,5 @@
+.. _install:
+
 Installation
 ============
 
@@ -6,6 +8,8 @@ Installation
 
 The comodojo dispatcher framework can be installed using `composer`_ as a product (using the dedicated `dispatcher project package`_) or as a library.
 
+.. _install-product:
+
 Install dispatcher as a product
 -------------------------------
 
@@ -17,6 +21,8 @@ To install dispatcher as a product, simply run the composer create-project comma
 
 Composer will install the dependencies and create the main configuration file. Once completed, configure the web server to use *dispatcher/public* as the document root.
 
+.. _install-library:
+
 Install dispatcher as a library
 -------------------------------
 

docs/plugins.rst

@@ -1,7 +1,7 @@
 .. _plugins:
 
-Plugins and events
-==================
+Plugins
+=======
 
 How dispatcher emits events
 ---------------------------

docs/routing.rst

@@ -208,6 +208,7 @@ Add a route programmatically
 In order to install a new route programmatically, the access to the ``\Comodojo\Dispatcher\Dispatcher`` object is required *before* invoking the ``Dispatcher::dispatch()`` method. Once gained, the main class can be used to get the router instance and then its routing table.
 
 .. code-block:: php
+    :linenos:
 
     $dispatcher = new \Comodojo\Dispatcher\Dispatcher();
 
@@ -222,6 +223,7 @@ In the routing table there are two methods that allow the installation of the ro
     The ``Table::add()`` method can be used to install a single route:
 
     .. code-block:: php
+        :linenos:
 
         $table->add(
             'routes/test/{"page": "p(\\d+)"}', // Route definition
@@ -240,6 +242,7 @@ In the routing table there are two methods that allow the installation of the ro
     This method is used to load one or multiple *permanent* route(s). The routes have to be passed as an array:
 
     .. code-block:: php
+        :linenos:
 
         $table->load(
             [
@@ -263,6 +266,7 @@ In the routing table there are two methods that allow the installation of the ro
     ``Table::load()``, instead, is designed to load a bunch of routes once and permanently (at least for the routing-table-cache ttl), and so it'is mostly useful in the framework startup. The `comodojo/dispatcher`_ project package, for example, adopt the following strategy to evaluate the router status and, in case, load the routing table from file:
 
     .. code-block:: php
+        :linenos:
 
         if (
             file_exists($routes_file) &&
@@ -285,6 +289,7 @@ There are some cases in which the request, after being evaluated, should pass th
 To bypass the router, it is possible to create a plugin that install a listener to a pre-routing event, like the following one:
 
 .. code-block:: php
+    :linenos:
 
     <?php namespace My\Awesome;
 
@@ -327,6 +332,7 @@ In some other cases, afer a route has been found, the service should run only if
 To skip the service, it is possible to create a plugin that installs a listener to a post-routing event and uses the ``Router::bypassService()`` method, like the following one:
 
 .. code-block:: php
+    :linenos:
 
     <?php namespace My\Awesome;