--- a/{{cookiecutter.project_slug}}/etc/development.ini	Thu Mar 22 19:07:57 2018 +0100
+++ b/{{cookiecutter.project_slug}}/etc/development.ini	Fri Mar 23 14:13:49 2018 +0100
@@ -1,3 +1,6 @@
+###
+### Standard Pyramid configuration
+###
 
 [app:main]
 use = egg:{{ cookiecutter.webapp_name }}
@@ -62,11 +65,11 @@
 retry.attempts = 3
 zodbconn.uri = zconfig://%(here)s/zodb-{{ cookiecutter.db_type }}.conf
 
-# By default, the toolbar only appears for clients from IP addresses
-# '127.0.0.1' and '::1'.
+## By default, the toolbar only appears for clients from IP addresses
+## '127.0.0.1' and '::1'.
 debugtoolbar.hosts = 127.0.0.1 ::1
 
-# fanstatic settings
+## Fanstatic settings
 fanstatic.use_application_uri = true
 fanstatic.publisher_signature = --static--
 fanstatic.versioning = true
@@ -76,12 +79,12 @@
 
 {%- if cookiecutter.use_elasticsearch.lower() in ('true','on','yes','1') %}
 
-# ElasticSearch settings
+## ElasticSearch settings
 elastic.servers = {{ cookiecutter.elasticsearch_server }}
 elastic.index = {{ cookiecutter.elasticsearch_index }}
 {%- endif %}
 
-# Beaker session
+## Beaker session settings
 beaker.session.type = {{ cookiecutter.beaker_backend }}
 beaker.session.url = {{ cookiecutter.beaker_server }}
 {%- if cookiecutter.beaker_backend == 'redis' %}
@@ -90,7 +93,7 @@
 beaker.session.data_dir = $((INSTALL))/var/cache
 beaker.session.lock_dir = $((INSTALL))/var/locks
 
-# Beaker cache
+## Beaker cache settings
 beaker.cache.type = {{ cookiecutter.beaker_backend }}
 beaker.cache.url = {{ cookiecutter.beaker_server }}
 beaker.cache.data_dir = $((INSTALL))/var/cache
@@ -109,63 +112,112 @@
 beaker.cache.views.db = 6
 {%- endif %}
 
-# PyAMS application factory
-pyams.application_factory = pyams_content.root.SiteRoot
-pyams.application_name = pyams
+
+###
+### PyAMS custom settings
+###
 
-# Secure PyAMS authentication policy (requires HTTPS)
+## PyAMS application factory
+## Default application factory is defined into PyAMS via a registered utility
+## You can override this factory by defining this setting or by providing your own utility
+# pyams.application_factory = pyams_content.root.SiteRoot
+# pyams.application_name = application
+
+## Secure PyAMS authentication policy (requires HTTPS)
 pyams.authentication_policy.secure = False
 
-# PyAMS mailer
+## PyAMS mailer
 pyams_mail.mailers = {{ cookiecutter.smtp_server_name }}.
 {{ cookiecutter.smtp_server_name }}.name = {{ cookiecutter.smtp_server_name }}
 {{ cookiecutter.smtp_server_name }}.host = {{ cookiecutter.smtp_server }}
 {{ cookiecutter.smtp_server_name }}.queue_path = $((INSTALL))/var/mail
 
-# PyAMS ØMQ TCP handlers
+## PyAMS ØMQ TCP handlers
+## These handlers are used by several application processes started by PyAMS application on startup.
+## For each process, you can define:
+## - the handler IP address (using "ip_address:port" syntax)
+## - a boolean flag to specify if the matching process should be started; if you are not on the "main" application
+##   process, the answer should be 'false'
+## - a "login:password" authentication credentials to be used (between server and clients)
+## - a list of allowed clients
+
+## Tasks scheduler process settings
 pyams_scheduler.tcp_handler = {{ cookiecutter.pyams_scheduler }}
 pyams_scheduler.start_handler = {{ cookiecutter.start_scheduler }}
 pyams_scheduler.allow_auth = admin:admin
 pyams_scheduler.allow_clients = 127.0.0.1
 
+## Medias converter process settings
 pyams_media.tcp_handler = {{ cookiecutter.pyams_medias_converter }}
 pyams_media.start_handler = {{ cookiecutter.start_medias_converter }}
 pyams_media.allow_auth = admin:admin
 pyams_media.allow_clients = 127.0.0.1
 
+## Elasticsearch indexer process settings
 pyams_content.es.tcp_handler = {{ cookiecutter.pyams_es_indexer }}
 pyams_content.es.start_handler = {{ cookiecutter.start_es_indexer }}
 pyams_content.es.allow_auth = admin:admin
 pyams_content.es.allow_clients = 127.0.0.1
 
+## Notifications server settings
+## PyAMS provides a websockets Gunicorn server which can be used to handle user notifications
 pyams_notify.tcp_handler = {{ cookiecutter.pyams_ws_notify }}
 pyams_notify_ws.cache_server = {{ cookiecutter.beaker_backend }}://{{ cookiecutter.beaker_server }}
 
 
-# PyAMS content settings
+## PyAMS languages settings
+## Lexicon languages are used by NLTK tokenizers to handle full-text indexing
+## Activate additional languages if required
 pyams_content.lexicon.languages = {{ cookiecutter.lexicon_languages }}
 
-pyams_content.config.tools_name = tools
+
+## PyAMS references tables configuration
+## This configuration is used by database upgrade process (see 'pyams_upgrade' command line script)
+## Settings are not used after database upgrade is complete
+
+## References tables container name
+# pyams_content.config.tables_name = references
 
-# Set factory to 'NONE' or '--' to disable tool registration
-pyams_content.config.views_tool_factory = pyams_content.shared.view.manager.ViewsManager
-pyams_content.config.views_tool_name = views
+## Pictograms tables name
+# pyams_content.config.pictograms_table_name = pictograms
+
 
-pyams_content.config.logos_tool_factory = pyams_content.shared.logo.manager.LogosManager
-pyams_content.config.logos_tool_name = logos
+## PyAMS shared tools configuration
+## This configuration is used by database upgrade process (see 'pyams_upgrade' command line script)
+## Settings are not used after database upgrade is complete
+
+## Shared tools container name
+# pyams_content.config.tools_name = tools
 
-pyams_content.config.imagemaps_tool_factory = pyams_content.shared.imagemap.manager.ImageMapsManager
-pyams_content.config.imagemaps_tool_name = imgmaps
+## Shared tools configuration
+## For each shared tool, you can define:
+## - a factory name; set value to 'NONE' or '--' to disable tool registration
+## - a tool name
+## Default values are defined for both into PyAMS_content package via factory adapters.
+## You can override default factory by defining these settings or by providing your own adapters.
+# pyams_content.config.views_tool_factory = pyams_content.shared.view.manager.ViewsManager
+# pyams_content.config.views_tool_name = views
+# pyams_content.config.logos_tool_factory = pyams_content.shared.logo.manager.LogosManager
+# pyams_content.config.logos_tool_name = logos
+# pyams_content.config.imagemaps_tool_factory = pyams_content.shared.imagemap.manager.ImageMapsManager
+# pyams_content.config.imagemaps_tool_name = imgmaps
+# pyams_content.config.forms_tool_factory = pyams_content.shared.form.manager.FormsManager
+# pyams_content.config.forms_tool_name = forms
+# pyams_content.config.news_tool_factory = pyams_content.shared.news.manager.NewsManager
+# pyams_content.config.news_tool_name = news
 
-pyams_content.config.forms_tool_factory = pyams_content.shared.form.manager.FormsManager
-pyams_content.config.forms_tool_name = forms
-
-pyams_content.config.news_tool_factory = pyams_content.shared.news.manager.NewsManager
-pyams_content.config.news_tool_name = news
+## Shared contents configuration
+## Default factories are defined into PyAMS_content package via factory adapters.
+## You can override default factory by defining these settings or by providing your own adapters.
+# pyams_content.config.blog_factory = pyams_content.shared.blog.manager.BlogManager
+# pyams_content.config.blogpost_factory = pyams_content.shared.blog.BlogPost
+# pyams_content.config.site_factory = pyams_content.shared.site.manager.SiteManager
+# pyams_content.config.folder_factory = pyams_content.shared.site.folder.SiteFolder
+# pyams_content.config.topic_factory = pyams_content.shared.site.Topic
 
 
 ###
-# wsgi server configuration
+### WSGI server configuration
 ###
 
 [server:main]
@@ -177,7 +229,7 @@
 
 
 ###
-# logging configuration
+### logging configuration
 ###
 
 [loggers]

--- a/{{cookiecutter.project_slug}}/etc/production.ini	Thu Mar 22 19:07:57 2018 +0100
+++ b/{{cookiecutter.project_slug}}/etc/production.ini	Fri Mar 23 14:13:49 2018 +0100
@@ -1,3 +1,6 @@
+###
+### Standard Pyramid configuration
+###
 
 [app:main]
 use = egg:{{ cookiecutter.webapp_name }}
@@ -61,7 +64,7 @@
 retry.attempts = 3
 zodbconn.uri = zconfig://%(here)s/zodb-{{ cookiecutter.db_type }}.conf
 
-# fanstatic settings
+## Fanstatic settings
 fanstatic.use_application_uri = true
 fanstatic.publisher_signature = --static--
 fanstatic.versioning = true
@@ -71,12 +74,12 @@
 
 {%- if cookiecutter.use_elasticsearch.lower() in ('true','on','yes','1') %}
 
-# ElasticSearch settings
+## ElasticSearch settings
 elastic.servers = {{ cookiecutter.elasticsearch_server }}
 elastic.index = {{ cookiecutter.elasticsearch_index }}
 {%- endif %}
 
-# Beaker session
+## Beaker session settings
 beaker.session.type = {{ cookiecutter.beaker_backend }}
 beaker.session.url = {{ cookiecutter.beaker_server }}
 {%- if cookiecutter.beaker_backend == 'redis' %}
@@ -85,7 +88,7 @@
 beaker.session.data_dir = $((INSTALL))/var/cache
 beaker.session.lock_dir = $((INSTALL))/var/locks
 
-# Beaker cache
+## Beaker cache settings
 beaker.cache.type = {{ cookiecutter.beaker_backend }}
 beaker.cache.url = {{ cookiecutter.beaker_server }}
 beaker.cache.data_dir = $((INSTALL))/var/cache
@@ -104,63 +107,117 @@
 beaker.cache.views.db = 6
 {%- endif %}
 
-# PyAMS application factory
-pyams.application_factory = pyams_content.root.SiteRoot
-pyams.application_name = pyams
+
+###
+### PyAMS custom settings
+###
 
-# Secure PyAMS authentication policy (requires HTTPS)
+## PyAMS application factory
+## Default application factory is defined into PyAMS via a registered utility
+## You can override this factory by defining this setting or by providing your own utility
+# pyams.application_factory = pyams_content.root.SiteRoot
+# pyams.application_name = application
+
+## Secure PyAMS authentication policy (requires HTTPS)
 pyams.authentication_policy.secure = True
 
-# PyAMS mailer
+## PyAMS mailer
 pyams_mail.mailers = {{ cookiecutter.smtp_server_name }}.
 {{ cookiecutter.smtp_server_name }}.name = {{ cookiecutter.smtp_server_name }}
 {{ cookiecutter.smtp_server_name }}.host = {{ cookiecutter.smtp_server }}
 {{ cookiecutter.smtp_server_name }}.queue_path = $((INSTALL))/var/mail
 
-# PyAMS ØMQ TCP handlers
+## PyAMS ØMQ TCP handlers
+## These handlers are used by several application processes started by PyAMS application on startup.
+## For each process, you can define:
+## - the handler IP address (using "ip_address:port" syntax)
+## - a boolean flag to specify if the matching process should be started; if you are not on the "main" application
+##   process, the answer should be 'false'
+## - a "login:password" authentication credentials to be used (between server and clients)
+## - a list of allowed clients
+
+## Tasks scheduler process settings
 pyams_scheduler.tcp_handler = {{ cookiecutter.pyams_scheduler }}
 pyams_scheduler.start_handler = {{ cookiecutter.start_scheduler }}
 pyams_scheduler.allow_auth = admin:admin
 pyams_scheduler.allow_clients = 127.0.0.1
 
+## Medias converter process settings
 pyams_media.tcp_handler = {{ cookiecutter.pyams_medias_converter }}
 pyams_media.start_handler = {{ cookiecutter.start_medias_converter }}
 pyams_media.allow_auth = admin:admin
 pyams_media.allow_clients = 127.0.0.1
 
+## Elasticsearch indexer process settings
 pyams_content.es.tcp_handler = {{ cookiecutter.pyams_es_indexer }}
 pyams_content.es.start_handler = {{ cookiecutter.start_es_indexer }}
 pyams_content.es.allow_auth = admin:admin
 pyams_content.es.allow_clients = 127.0.0.1
 
+## Notifications server settings
+## PyAMS provides a websockets Gunicorn server which can be used to handle user notifications
 pyams_notify.tcp_handler = {{ cookiecutter.pyams_ws_notify }}
 pyams_notify_ws.cache_server = {{ cookiecutter.beaker_backend }}://{{ cookiecutter.beaker_server }}
 
 
-# PyAMS content settings
+## PyAMS languages settings
+## Lexicon languages are used by NLTK tokenizers to handle full-text indexing
+## Activate additional languages if required
 pyams_content.lexicon.languages = {{ cookiecutter.lexicon_languages }}
 
-pyams_content.config.tools_name = tools
+
+## PyAMS references tables configuration
+## This configuration is used by database upgrade process (see 'pyams_upgrade' command line script)
+## Settings are not used after database upgrade is complete
+
+## References tables container name
+# pyams_content.config.tables_name = references
 
-# Set factory to 'NONE' or '--' to disable tool registration
-pyams_content.config.views_tool_factory = pyams_content.shared.view.manager.ViewsManager
-pyams_content.config.views_tool_name = views
+## Pictograms tables name
+#pyams_content.config.pictograms_table_name = pictograms
+
 
-pyams_content.config.logos_tool_factory = pyams_content.shared.logo.manager.LogosManager
-pyams_content.config.logos_tool_name = logos
+## PyAMS shared tools configuration
+## This configuration is used by database upgrade process (see 'pyams_upgrade' command line script)
+## Settings are not used after database upgrade is complete
+
+## Shared tools container name
+# pyams_content.config.tools_name = tools
 
-pyams_content.config.imagemaps_tool_factory = pyams_content.shared.imagemap.manager.ImageMapsManager
-pyams_content.config.imagemaps_tool_name = imgmaps
+## Shared tools configuration
+## For each shared tool, you can define:
+## - a factory name; set value to 'NONE' or '--' to disable tool registration
+## - a tool name
+## Default values are defined for both into PyAMS_content package via factory adapters.
+## You can override default factory by defining these settings or by providing your own adapters.
+
+# pyams_content.config.views_tool_factory = pyams_content.shared.view.manager.ViewsManager
+# pyams_content.config.views_tool_name = views
+
+# pyams_content.config.logos_tool_factory = pyams_content.shared.logo.manager.LogosManager
+# pyams_content.config.logos_tool_name = logos
 
-pyams_content.config.forms_tool_factory = pyams_content.shared.form.manager.FormsManager
-pyams_content.config.forms_tool_name = forms
+# pyams_content.config.imagemaps_tool_factory = pyams_content.shared.imagemap.manager.ImageMapsManager
+# pyams_content.config.imagemaps_tool_name = imgmaps
+
+# pyams_content.config.forms_tool_factory = pyams_content.shared.form.manager.FormsManager
+# pyams_content.config.forms_tool_name = forms
+
+# pyams_content.config.news_tool_factory = pyams_content.shared.news.manager.NewsManager
+# pyams_content.config.news_tool_name = news
 
-pyams_content.config.news_tool_factory = pyams_content.shared.news.manager.NewsManager
-pyams_content.config.news_tool_name = news
+## Shared contents configuration
+## Default factories are defined into PyAMS_content package via factory adapters.
+## You can override default factory by defining these settings or by providing your own adapters.
+# pyams_content.config.blog_factory = pyams_content.shared.blog.manager.BlogManager
+# pyams_content.config.blogpost_factory = pyams_content.shared.blog.BlogPost
+# pyams_content.config.site_factory = pyams_content.shared.site.manager.SiteManager
+# pyams_content.config.folder_factory = pyams_content.shared.site.folder.SiteFolder
+# pyams_content.config.topic_factory = pyams_content.shared.site.Topic
 
 
 ###
-# wsgi server configuration
+### WSGI server configuration
 ###
 
 [server:main]
@@ -172,7 +229,7 @@
 
 
 ###
-# logging configuration
+### logging configuration
 ###
 
 [loggers]