diff -r 6ed429390935 -r 5ebe61e3a965 src/source/appconfig.rst
--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/src/source/appconfig.rst	Fri Apr 27 11:51:08 2018 +0200
@@ -0,0 +1,80 @@
+.. _config:
+
+PyAMS configuration
+===================
+
+.. Note::
+
+    PyAMS application configuration is done via several complementary ways:
+
+        - via **Pyramid's configuration** files located in 'etc/' folder
+
+        - via **ZCML files** .
+
+        - via **Site Management** to setup Local utilities defined into ZODB (see :ref:`appmanage`)
+
+
+Pyramid's configuration files
+-----------------------------
+
+PyAMS is using default Pyramid's ini_ configuration files to define settings. When using default PyAMS scaffold, these
+INI files are stored into *etc* folder. Two files are created by scaffold: a development file (*development.ini*) and
+a production file (*production.ini*) which contain nearly the same directives, except for debug toolbar (activated only
+in development), Fanstatic configuration and logging.
+
+.. _ini: https://docs.pylonsproject.org/projects/pyramid/en/latest/narr/project.html#development-ini
+
+These files are actually documented, but here are a few important directives:
+
+- **zodbconn.uri**: (ex: zconfig:/zodb-relstorage.conf)
+
+- **pyams.application_name**: Name of your own application
+- **pyams.application_factory**: Configuration module path to your custom application.
+
+- **pyams_xxx.tcp_handler** :  Adress of the tcp handler for the service associated to the pyams package
+- **pyams_xxx.start_handler**: True / False
+
+- **pyams_content.config.xxx_tool_factory** and **pyams_content.config.xxx_tool_name**: You can override default factory by defining these settings or by providing your own adapters.
+
+
+
+Pyramid's configuration files powered by PyAMS_utils
+----------------------------------------------------
+
+On application startup, if PyAMS_utils package is included into Pyramid configuration, several operations take
+place:
+
+ - a custom **site factory** is defined
+
+ - custom request methods are defined
+
+ - a custom **traverser** handling **namespaces** is defined
+
+ - a custom subscribers predicate based on interfaces support is defined
+
+ - several adapters are registered, to handle annotations and key references
+
+ - custom TALES extensions are registered.
+
+The site factory is an important component in this process. It is this factory which will define the application root
+and create a **local site manager**.
+
+Pyramid application is loaded from ZODB's root via a key defined in Pyramid's configuration file; the key is named
+*pyams.application_name* and it's default value is *application*.
+
+If the application can't be found, PyAMS is looking for an application class name in Pyramid's configuration file; the
+class name configuration key is called *pyams.application_factory* and defined by default as
+*pyams_utils.site.BaseSiteRoot*. PyAMS default site factory will then create the application, and add a local site
+manager to it (see :ref:`zca`).
+
+After application creation, a :py:class:`NewLocalSiteCreatedEvent <pyams_utils.site.NewLocalSiteCreatedEvent>` is
+notified. Custom packages can subscribe to this event to register custom components.
+
+
+
+ZCML configuration files
+------------------------
+
+Adding more ZCML configuration directives is not mandatory in any way but can be useful in several use cases. For
+example, templates can't be overriden via Python annotations without creating a new subclass; this can be done
+easily via ZCML.