--- a/buildout.cfg Fri Apr 27 14:44:33 2018 +0200
+++ b/buildout.cfg Wed May 16 14:03:44 2018 +0200
@@ -1,5 +1,5 @@
[buildout]
-extensions = buildout.wheel
+#extensions = buildout.wheel
eggs-directory = /var/local/env/pyams/eggs
extends = http://download.ztfy.org/pyams/pyams-dev.cfg
find-links = http://download.ztfy.org/eggs
@@ -10,12 +10,6 @@
show-picked-versions = true
newest = false
-allow-hosts =
- bitbucket.org
- *.python.org
- *.sourceforge.net
- github.com
-
versions = versions
develop =
.
@@ -86,6 +80,7 @@
pyams_zmi
pyams_zmq
pyams_zodbbrowser
+ repoze.lru
zc.lockfile
interpreter = ${buildout:directory}/bin/py
@@ -93,6 +88,7 @@
recipe = collective.recipe.sphinxbuilder
eggs =
${package:eggs}
+ repoze.sphinx.autointerface
sphinx_rtd_theme
source = ${buildout:directory}/src/source
build = ${buildout:directory}/src/build
--- a/requirements.txt Fri Apr 27 14:44:33 2018 +0200
+++ b/requirements.txt Wed May 16 14:03:44 2018 +0200
@@ -38,6 +38,7 @@
pyramid-fanstatic==0.5
pyramid-zodbconn==0.7
pyzmq==16.0.4
+repoze.lru = 0.7
repoze.sphinx.autointerface==0.8
Sphinx==1.6.7
sphinx_rtd_theme==0.2.4
--- a/setup.py Fri Apr 27 14:44:33 2018 +0200
+++ b/setup.py Wed May 16 14:03:44 2018 +0200
@@ -62,7 +62,9 @@
extras_require=dict(test=tests_require),
install_requires=[
'setuptools',
- 'sphinx_rtd_theme'
+ 'repoze.lru',
+ 'repoze.sphinx.autointerface',
+ 'sphinx_rtd_theme',
# -*- Extra requirements: -*-
],
entry_points={})
--- a/src/pyams_user_guide.egg-info/requires.txt Fri Apr 27 14:44:33 2018 +0200
+++ b/src/pyams_user_guide.egg-info/requires.txt Wed May 16 14:03:44 2018 +0200
@@ -1,4 +1,6 @@
setuptools
+repoze.lru
+repoze.sphinx.autointerface
sphinx_rtd_theme
[test]
--- /dev/null Thu Jan 01 00:00:00 1970 +0000
+++ b/src/source/appextend.rst Wed May 16 14:03:44 2018 +0200
@@ -0,0 +1,167 @@
+.. _appextend:
+
+How to create a new Portlet ?
+-----------------------------
+
+**Portlets** are pluggable user interface software components that are managed and displayed in a web portal,
+for example an enterprise portal or a web CMS. A portlet can aggregate (integrate) and personalize content from
+different sources within a web page. A portlet responds to requests from a web client and generates dynamic content
+(*reference:* `Wiki portlet`_).
+
+.. _`wiki portlet`: https://en.wikipedia.org/wiki/Portlet
+
+
+**PyAMS Portal** provides the portal engine but only a very small set of predefined portlets that can be used to compose
+and organize the structure of a web page; additional portlets are provided by other packages, like
+:ref:`pyams_content`.
+
+
+1. Define portlet settings
+''''''''''''''''''''''''''
+
+Portlet settings interface are defined in ``interfaces.py``, you can use :py:class:`pyams_portal.interfaces.IPortletSettings`
+or extend the interface by adding additional properties for example:
+
+.. code-block:: python
+
+ from zope.schema import Text
+
+ NEW_PORTLET_NAME = 'new.portlet'
+
+ class INewPortletSettings(IPortletSettings):
+
+ comment = Text(title=_("Comment"),
+ required=True)
+
+
+A :py:class:`pyams_portal.portlet.PortletSettings` persistent subclass then implements what IPortletSettings describes:
+
+.. code-block:: python
+
+ @implementer(INewPortletSettings)
+ class NewPortletSettings(PortletSettings):
+ """Portlet settings"""
+
+ comment = FieldProperty(INewPortletSettings['comment'])
+
+
+2. Create Portlet
+'''''''''''''''''
+
+The Portlet component is a utility, which implements the :py:class:`pyams_portal.interfaces.IPortlet` interface and is
+registered by the :py:func:`pyams_portal.portlet.portlet_config` decorator;
+
+.. code-block:: python
+
+ @portlet_config(permission=VIEW_PERMISSION)
+ class ImagePortlet(Portlet):
+ """Image portlet"""
+
+ name = NEW_PORTLET_NAME
+ label = _("New portlet")
+
+ toolbar_image = None
+ toolbar_css_class = 'fa fa-fw fa-2x fa-picture-o'
+
+ settings_class = NewPortletSettings
+
+
+Where:
+ - **permission**: permission required to display this portlet content
+ - **name**: internal name given to this portlet. This name must be unique between all portlets, so using your own
+ namespace into this name is generally a good option!
+ - **label**: user label given to this portlet
+ - **toolbar_image**: URL of an image used to display portlet button into ZMI toolbar, if any
+ - **toolbar_css_class**: CSS class used to display portlet button into ZMI toolbar, if any
+ - **settings_class**: class used to store portlet settings.
+
+
+3. Create portlet settings edit form
+''''''''''''''''''''''''''''''''''''
+
+Portlet settings have to be updated through management interface via a :py:class:`pyams_portal.zmi.portlet.PortletSettingsEditor`
+subform:
+
+.. code-block:: python
+
+ @pagelet_config(name='properties.html', context=INewPortletSettings, layer=IPyAMSLayer,
+ permission=VIEW_SYSTEM_PERMISSION)
+ class NewPortletSettingsEditor(PortletSettingsEditor):
+ """New portlet settings editor"""
+
+ settings = INewPortletSettings
+
+
+ @adapter_config(name='properties.json', context=(INewPortletSettings, IPyAMSLayer), provides=IPagelet)
+ class NewPortletSettingsAJAXEditor(AJAXEditForm, NewPortletSettingsEditor):
+ """New portlet settings editor, JSON renderer"""
+
+
+4. Previewing portlet content
+'''''''''''''''''''''''''''''
+
+A *previewer* is used into ZMI to display portlet content into portal template definition page:
+
+.. code-block:: python
+
+ @adapter_config(context=(Interface, IPyAMSLayer, Interface, INewPortletSettings), provides=IPortletPreviewer)
+ @template_config(template='my-portlet-preview.pt', layer=IPyAMSLayer)
+ class NewPortletPreviewer(PortletPreviewer):
+ """New portlet previewer"""
+
+
+The previewer template is a Chameleon template:
+
+.. code-block:: genshi
+
+ <tal:var define="settings view.settings">
+ <tal:if condition="settings.visible">
+ <div tal:content="settings.comment">Comment</div>
+ </tal:if>
+ <tal:if condition="not settings.visible">
+ <div class="text-center padding-y-5">
+ <span class="fa-stack fa-lg">
+ <i class="fa fa-eye fa-stack-1x"></i>
+ <i class="fa fa-ban fa-stack-2x text-danger"></i>
+ </span>
+ </div>
+ </tal:if>
+ </tal:var>
+
+Here we check if portlet is visible or not to display a small icon when hidden; otherwise we display entered comment.
+
+
+5. Rendering portlet content
+''''''''''''''''''''''''''''
+
+A *renderer* is used to display portlet content into rendered page content:
+
+.. code-block:: python
+
+ @adapter_config(context=(IPortalContext, IPyAMSLayer, Interface, INewPortletSettings), provides=IPortletRenderer)
+ @template_config(template='my-portlet-render.pt', layer=IPyAMSLayer)
+ class NewPortletRenderer(PortletRenderer):
+ """New portlet renderer"""
+
+ label = _("Default comment renderer")
+
+
+Each renderer template is also a Chameleon template:
+
+.. code-block:: genshi
+
+ <div class="comment" tal:content="view.settings.comment">Comment</div>
+
+
+This is the configuration of a *default* renderer defined for this portlet; you can provide several renderers for a
+given portlet by given distinct names to the adapters:
+
+.. code-block:: python
+
+ @adapter_config(name='another-renderer',
+ context=(IPortalContext, IPyAMSLayer, Interface, INewPortletSettings), provides=IPortletRenderer)
+ @template_config(template='my-portlet-render-2.pt', layer=IPyAMSLayer)
+ class AnotherNewPortletRenderer(PortletRenderer):
+ """Another new portlet renderer"""
+
+ label = _("Another comment renderer")
--- a/src/source/appinstall.rst Fri Apr 27 14:44:33 2018 +0200
+++ b/src/source/appinstall.rst Wed May 16 14:03:44 2018 +0200
@@ -229,7 +229,7 @@
.. _zodbinit:
Initializing the ZODB database
-==============================
+------------------------------
After, you have downloaded and installed all required packages, you have to initialize the database so that all
required components are available.
@@ -242,80 +242,3 @@
This process requires that every package is correctly included into *pyramid.includes* directive from selected
configuration file.
-
-
-Initializing Elasticsearch index
-================================
-
-If you want to use an Elasticsearch index, you have to initialize index settings and mappings; the Ingest attachment
-plug-in is also required to handle attachments correctly.
-
-Elasticsearch integration is defined through the *PyAMS_content_es* package. Configuration files are available in this
-package, for attachment pipeline, index settings and mappings:
-
-.. code-block:: bash
-
- (env) $ cd /var/local/src/pyams/pyams_content_es
- (env) $ curl --noproxy localhost -XDELETE http://localhost:9200/pyams (1)
- (env) $ curl --noproxy localhost -XPUT http://localhost:9200/pyams -d @index-settings.json
-
- (env) $ curl --noproxy localhost -XPUT http://localhost:9200/pyams/WfNewsEvent/_mapping -d @mappings/WfNewsEvent.json
- (env) $ curl --noproxy localhost -XPUT http://localhost:9200/pyams/WfTopic/_mapping -d @mappings/WfTopic.json
- (env) $ curl --noproxy localhost -XPUT http://localhost:9200/pyams/WfBlogPost/_mapping -d @mappings/WfBlogPost.json
-
-(1) If 'pyams' is defined as Elasticsearch index name.
-
-
-Initializing NLTK
-=================
-
-Some NLTK (Natural Language Toolkit) tokenizers and stopwords utilities are used to index fulltext contents elements.
-This package requires downloading and configuration of several elements which are done as follow:
-
-.. code-block:: bash
-
- (end) $ ./bin/py
- >>> import nltk
- >>> nltk.download()
- NLTK Downloader
- ---------------------------------------------------------------------------
- d) Download l) List u) Update c) Config h) Help q) Quit
- ---------------------------------------------------------------------------
- Downloader> c
-
- Data Server:
- - URL: <https://raw.githubusercontent.com/nltk/nltk_data/gh-pages/index.xml>
- - 6 Package Collections Available
- - 107 Individual Packages Available
-
- Local Machine:
- - Data directory: /home/tflorac/nltk_data
-
- ---------------------------------------------------------------------------
- s) Show Config u) Set Server URL d) Set Data Dir m) Main Menu
- ---------------------------------------------------------------------------
- Config> d
- New directory> /usr/local/lib/nltk_data (1)
- Config> m
-
- ---------------------------------------------------------------------------
- d) Download l) List u) Update c) Config h) Help q) Quit
- ---------------------------------------------------------------------------
- Downloader> d
-
- Download which package (l=list; x=cancel)?
- Identifier> punkt
- Downloading package punkt to /usr/local/lib/nltk_data...
-
- Downloader> d
-
- Download which package (l=list; x=cancel)?
- Identifier> stopwords
- Downloading package stopwords to /usr/local/lib/nltk_data...
-
-
-(1) On Debian GNU/Linux, you can choose any directory between '*~/nltk_data*' (where '~' is the homedir of user running
-Pyramid application), '*/usr/share/nltk_data*', '*/usr/local/share/nltk_data*', '*/usr/lib/nltk_data*' and
-'*/usr/local/lib/nltk_data*'.
-
-
--- a/src/source/appmanage.rst Fri Apr 27 14:44:33 2018 +0200
+++ b/src/source/appmanage.rst Wed May 16 14:03:44 2018 +0200
@@ -10,7 +10,7 @@
When the PyAMS is initialized, it create and register several utilities into the *local registry* and saved into ZODB.
These utilities are created with default values which can be modified through **management interface** when
-the application is started.
+the application is started by default (http://localhost:6543/admin).
Local registry utilities
@@ -21,33 +21,59 @@
Some important utilities include:
-- a **catalog**: the catalog has the responsibility to index every content properties which are required to make quick
- and efficient searches. Catalog indexes are automatically created on database upgrade; management interface
- allows administrator to get indexes properties, to get the number of indexed objects and values for a given index, and
- to delete an index before recreating it by running the database upgrade script another time (see :ref:`scripts`).
+**Catalog**:
+ The catalog has the responsibility to index every content properties which are required to make quick
+ and efficient searches. Catalog indexes are automatically created on database upgrade; management interface
+ allows administrator to get indexes properties, to get the number of indexed objects and values for a given index, and
+ to delete an index before recreating it by running the database upgrade script another time (see :ref:`scripts`).
-- an **internal IDs** utility:
+**Internal IDs** utility:
+ The catalog object doesn't store direct references to objects, but their internal IDs which are generated by this
+ utility.
-- a **language negotiator**:
+**Language negotiator**:
+ As a web site or application can be localized, this utility allows you to define priorities between language
+ definition options (between *user session*, *browser* end *server*), and to define which languages are available
+ to your users (which is particularly important when managing potentially multi-lingual contents).
+
+ .. tip::
+ Static texts like those displayed into PyAMS management interface are always translated to the language defined
+ into browser language, if available.
-- a **portal templates** container:
+**Portal templates** container:
+ Portal templates are used to define *presentation templates* based on *portlets* (see :ref:`pyams_portal`). You can
+ create *local* templates, or create *shared templates* into this utility which can then be reused into several
+ places in your web site.
-- a **security manager**:
+**Security manager**:
+ This utility is used to define authentication sources which will be available to authenticate your users.
+ :ref:`pyams_security` package provides several authentication modules (like local users, or via OAuth/OAuth2
+ providers); :ref:`pyams_ldap` add authentication plug-in via an LDAP directory.
-- a **sequential IDs** utility:
+**Sequential IDs** utility:
+ This utility is used to assign simple sequential IDs to site contents (like sites, news, topics and more); these
+ IDs are simple to identify a given content; several versions of a given content handle by workflow share the same
+ sequential ID.
-- a **server timezone** utility:
+**Server timezone** utility:
+ Define the timezone server to display date and time accordingly.
-- a **user profiles** container:
+**User profiles** container:
+ This utility is used to store information associated to principals through their user profile.
Optional utilities can also include:
-- an **Elasticsearch content indexer**:
+**Elasticearch content indexer**:
-- a **maps manager**:
+Verifier la connection entre le server ElasticSearch et la l'application PyAMS
-- a **medias converter**:
+**Maps manager**:
+Systeme de cartografie, avec OpenStreeMaps, WMS, GeoPortable, ESRI ou encore Google Maps
+permet de créer des zones catographique²
-- a **tasks scheduler**:
+**Medias converter**:
+
+**Tasks scheduler**:
+
--- a/src/source/conf.py Fri Apr 27 14:44:33 2018 +0200
+++ b/src/source/conf.py Wed May 16 14:03:44 2018 +0200
@@ -89,7 +89,7 @@
master_doc = 'index'
# General information about the project.
-project = 'PyAMS User Guide'
+project = 'PyAMS Documentation'
copyright = '2018, Thierry Florac'
author = 'Thierry Florac'
@@ -107,7 +107,7 @@
#
# This is also used if you do content translation via gettext catalogs.
# Usually you set "language" from the command line for these cases.
-language = None
+language = 'en'
# List of patterns, relative to source directory, that match files and
# directories to ignore when looking for source files.
@@ -117,10 +117,12 @@
# The name of the Pygments (syntax highlighting) style to use.
pygments_style = 'sphinx'
+# The default language to highlight source code in.
+highlight_language = 'python3'
+
# If true, `todo` and `todoList` produce output, else they produce nothing.
todo_include_todos = False
-
# -- Options for HTML output ----------------------------------------------
# The theme to use for HTML and HTML Help pages. See the documentation for
@@ -148,7 +150,7 @@
# -- Options for HTMLHelp output ------------------------------------------
# Output file base name for HTML help builder.
-htmlhelp_basename = 'PyAMSUserGuidedoc'
+htmlhelp_basename = 'PyAMSDocumentation'
# -- Options for LaTeX output ---------------------------------------------
@@ -175,7 +177,7 @@
# (source start file, target name, title,
# author, documentclass [howto, manual, or own class]).
latex_documents = [
- (master_doc, 'PyAMSUserGuide.tex', 'PyAMS User Guide Documentation',
+ (master_doc, 'PyAMSDocumentation.tex', 'PyAMS Documentation',
'Thierry Florac', 'manual'),
]
@@ -185,7 +187,7 @@
# One entry per manual page. List of tuples
# (source start file, name, description, authors, manual section).
man_pages = [
- (master_doc, 'pyamsuserguide', 'PyAMS User Guide Documentation',
+ (master_doc, 'PyAMSDocumentation', 'PyAMS Documentation',
[author], 1)
]
@@ -196,8 +198,8 @@
# (source start file, target name, title, author,
# dir menu entry, description, category)
texinfo_documents = [
- (master_doc, 'PyAMSUserGuide', 'PyAMS User Guide Documentation',
- author, 'PyAMSUserGuide', 'One line description of project.',
+ (master_doc, 'PyAMSDocumentation', 'PyAMS Documentation',
+ author, 'PyAMSDocumentation', 'PyAMS a CMS based on Pyramid and Zope',
'Miscellaneous'),
]
@@ -241,5 +243,6 @@
def setup(app):
+
app.add_stylesheet('css/custom.css')
--- a/src/source/developerguide.rst Fri Apr 27 14:44:33 2018 +0200
+++ b/src/source/developerguide.rst Wed May 16 14:03:44 2018 +0200
@@ -11,4 +11,8 @@
:maxdepth: 2
zca
- extend
+ package_layout
+ appextend
+ zmi_integration
+ traverser
+ tales
--- a/src/source/extend.rst Fri Apr 27 14:44:33 2018 +0200
+++ /dev/null Thu Jan 01 00:00:00 1970 +0000
@@ -1,13 +0,0 @@
-.. _extending:
-
-Extending PyAMS
-===============
-
-.. toctree::
- :maxdepth: 2
-
- package_layout
- traverser
- tales
-
-
--- a/src/source/index.rst Fri Apr 27 14:44:33 2018 +0200
+++ b/src/source/index.rst Wed May 16 14:03:44 2018 +0200
@@ -2,16 +2,12 @@
sphinx-quickstart on Tue Nov 15 16:18:42 2016.
You can adapt this file completely to your liking, but it should at least
contain the root `toctree` directive.
-
.. _index:
-
Contents
---------
-
-
.. toctree::
:maxdepth: 2
:caption: Getting started
@@ -29,14 +25,13 @@
.. toctree::
:maxdepth: 2
- :caption: Custom install documentation
+ :caption: Installation
ZODB Server <zodb>
- PyAMS Installation <appinstall>
+ Installing PyAMS <appinstall>
Configuring and Running PyAMS <app>
- PyAMS Site management (ZMI)<manage>
-
-
+ Managing PyAMS environment <manage>
+ Additional Plugins <plugins>
.. toctree::
--- a/src/source/introduction.rst Fri Apr 27 14:44:33 2018 +0200
+++ b/src/source/introduction.rst Wed May 16 14:03:44 2018 +0200
@@ -52,3 +52,39 @@
If you want to create a PyAMS application instance easily, just follow the :ref:`quickstart` guide!
If you want learn more about a custom installation follow :ref:`install` procedure.
+
+
+
+1.1. Overview
+
+Zope 2 is a free and open-source, object-oriented web application server written in the Python programming language. The term ZOPE is an acronym for “Z Object Publishing Environment” (the Z doesn’t really mean anything in particular). However, nowadays ZOPE is simply written as Zope. It has three distinct audiences.
+
+
+Developers
+ Individuals who wish to extend Zope to create highly customized solutions. This audience is likely interested in creating highly reusable custom code that makes Zope do something new and interesting. They will likely make heavy use of “through the file-system” style development.
+
+
+This guide is intended to document Zope for the second audience, Developers, as defined above. If you fit more into the “user” audience defined above, you’ll probably want to start by reading The Zope Book .
+
+Throughout this guide, it is assumed that you know how to program in the Python programming language. Most of the examples in this guide will be in Python. There are a number of great resources and books for learning Python; the best online resource is the python.org web site and many books can be found on the shelves of your local bookstore.
+1.2. Organization of the book
+
+This book describes Zope’s services to the developer from a hands on, example-oriented standpoint. This book is not a complete reference to the Zope API, but rather a practical guide to applying Zope’s services to develop and deploy your own web applications. This book covers the following topics:
+
+Getting Started
+ This chapter provides a brief overview of installation and getting started with application development.
+Components and Interfaces
+ Zope use a component-centric development model. This chapter describes the component model in Zope and how Zope components are described through interfaces.
+Object Publishing
+ Developing applications for Zope involves more than just creating a component, that component must be publishable on the web. This chapter describes publication, and how your components need to be designed to be published.
+Zope Products
+ New Zope components are distributed and installed in packages called “Products”. This chapter explains Products in detail.
+Persistent Components
+ Zope provides a built-in, transparent Python object database called ZODB. This chapter describes how to create persistent components, and how they work in conjunction with the ZODB.
+Acquisition
+ Zope relies heavily on a dynamic technique called acquisition. This chapter explores acquisition thoroughly.
+Security
+ When your component is used by many different people through the web, security becomes a big concern. This chapter describes Zope’s security API and how you can use it to make security assertions about your object.
+Debugging and Testing
+ Zope has built in debugging and testing support. This chapter describes these facilities and how you can debug and test your components.
+
--- a/src/source/packages.rst Fri Apr 27 14:44:33 2018 +0200
+++ b/src/source/packages.rst Wed May 16 14:03:44 2018 +0200
@@ -32,7 +32,7 @@
PyAMS Alchemy <pyams_alchemy/pyams_alchemy>
PyAMS Cache <pyams_cache/pyams_cache>
- PyAMS Content_es <pyams_content_es/pyams_content_es>
+ PyAMS Content with ElasticSearch <pyams_content_es/pyams_content_es>
PyAMS Default theme <pyams_default_theme/pyams_default_theme>
PyAMS File <pyams_file/pyams_file>
PyAMS GIS <pyams_gis/pyams_gis>
@@ -41,7 +41,7 @@
PyAMS Mail <pyams_mail/pyams_mail>
PyAMS Media <pyams_media/pyams_media>
PyAMS Notify <pyams_notify/pyams_notify>
- PyAMS Notify <pyams_notify_ws/pyams_notify_ws>
+ PyAMS Notify with WebSocket<pyams_notify_ws/pyams_notify_ws>
PyAMS Scheduler <pyams_scheduler/pyams_scheduler>
PyAMS Thesaurus <pyams_thesaurus/pyams_thesaurus>
PyAMS Security <pyams_security/pyams_security>
--- /dev/null Thu Jan 01 00:00:00 1970 +0000
+++ b/src/source/plugins.rst Wed May 16 14:03:44 2018 +0200
@@ -0,0 +1,209 @@
+.. _plugins:
+
+PyAMS additional features and services
+======================================
+
+
+Elasticsearch
++++++++++++++
+
+At first you need to install ElasticSearch (ES); PyAMS is actually compatible with version 5.4. The Ingest attachment
+plug-in is also required to handle attachments correctly.
+
+Visit https://www.elastic.co/ to learn how to install Elasticsearch Server and `ingest-attachment` plug-in
+
+
+.. tip:: Documentation for installing ElasticSearch 5.4
+
+ - https://www.elastic.co/guide/en/elasticsearch/reference/5.4/gs-installation.html
+ - https://www.elastic.co/guide/en/elasticsearch/plugins/5.4/ingest-attachment.html
+
+
+After Elasticsearch installation, following steps describe how to configure ES with PyAMS.
+
+
+Initializing Elasticsearch index
+--------------------------------
+
+If you want to use an Elasticsearch index, you have to initialize index settings and mappings;
+Elasticsearch integration is defined through the *PyAMS_content_es* package.
+
+
+1. Enable service
+'''''''''''''''''
+
+In Pyramid INI application files (*etc/development.ini* and *etc/production.ini*):
+
+.. code-block:: ini
+
+ # Elasticsearch server settings
+ elastic.server = http://127.0.0.1:9200
+ elastic.index = pyams
+
+Where:
+ - **elastic.server**: address of Elasticsearch server; you can include authentication arguments in the form
+ *http://login:password@w.x.y.z:9200*
+ - **elastic.index**: name of Elasticsearch index.
+
+
+On startup, main PyAMS application process can start in *indexer* process which will handle indexing requests in
+asynchronous mode; this process settings are defined like this:
+
+.. code-block:: ini
+
+ # PyAMS content Elasticsearch indexer process settings
+ pyams_content.es.tcp_handler = 127.0.0.1:5557
+ pyams_content.es.start_handler = false
+ pyams_content.es.allow_auth = admin:admin
+ pyams_content.es.allow_clients = 127.0.0.1
+
+Where:
+ - **pyams_content.es.tcp_handler**: IP address and listening port of PyAMS indexer process
+ - **pyams_content.es.start_handler**: if *true*, the indexer process is started on PyAMS startup; otherwise (typically
+ in a cluster configuration), the process is supposed to be started from another *master* server
+ - **pyams_content.es.allow_auth**: login and password to be used to connect to indexer process (settings are defined
+ in the same way on indexer process and on all it's clients)
+ - **pyams_content.es.allow_clients**: list of IP addresses allowed to connect to indexer process.
+
+
+2. Initialize Elasticsearch database
+''''''''''''''''''''''''''''''''''''
+
+Configuration files for attachment pipeline, index and mappings settings are available into `pyams_content_es` source
+package or in PyAMS installation folder:
+
+
+.. code-block:: bash
+
+ (env) $ cd docs/elasticsearch
+ (env) $ curl --noproxy localhost -XPUT http://localhost:9200/_ingest/pipeline/attachment -d @attachment-pipeline.json
+
+
+And with ``elastic.index = pyams`` defined as Elasticsearch index name: *"http://localhost:9200/pyams"*:
+
+.. code-block:: shell
+
+ (env) $ curl -XDELETE http://localhost:9200/pyams
+
+ (env) $ curl -XPUT http://localhost:9200/pyams -d @index-settings.json
+
+ (env) $ curl -XPUT http://localhost:9200/pyams/WfTopic/_mapping -d @mappings/WfTopic.json
+ (env) $ curl -XPUT http://localhost:9200/pyams/WfNewsEvent/_mapping -d @mappings/WfNewsEvent.json
+ (env) $ curl -XPUT http://localhost:9200/pyams/WfBlogPost/_mapping -d @mappings/WfBlogPost.json
+
+
+*Troubleshooting*: If you have a 406 error try to add ``-H 'Content-Type: application/json'`` in Curl command lines.
+
+
+3. Update index contents
+''''''''''''''''''''''''
+
+If your ZODB database already store contents, you can update ElasticSearch indexes with all these contents with
+``pymas_es_index`` command line script. From a shell:
+
+.. code-block:: bash
+
+ (env) $ ./bin/pyams_es_index ../etc/development.ini
+
+
+
+Natural Language Toolkit - NLTK
++++++++++++++++++++++++++++++++
+
+PyAMS is using NLTK features through the *PyAMS_calalog*.
+
+.. seealso::
+
+ Visit https://www.nltk.org/ to learn more about NLTK
+
+
+Initializing NLTK (Natural Language ToolKit)
+--------------------------------------------
+
+Some NLTK collections like **tokenizers** and **stopwords** utilities are used to index fulltext contents
+elements. You can enhance NLTK indexation according to your own needs. This package requires downloading and
+configuration of several elements which are done as follow:
+
+
+*1. Run the Python shell into PyAMS environment:*
+
+.. code-block:: bash
+
+ (env) $ ./bin/py
+
+
+*2. In the Python shell:*
+
+.. code-block:: pycon
+
+ >>> import nltk
+ >>> nltk.download()
+
+
+*3. Configuration installation directory:*
+
+.. tip::
+
+ On Debian GNU/Linux, you can choose any directory between '*~/nltk_data*' (where '~' is the homedir of user running
+ Pyramid application), '*/usr/share/nltk_data*', '*/usr/local/share/nltk_data*', '*/usr/lib/nltk_data*' and
+ '*/usr/local/lib/nltk_data*'
+
+ Please check if you have permission to write to this directory!
+
+
+.. code-block:: shell
+
+ NLTK Downloader
+ ---------------------------------------------------------------------------
+ d) Download l) List u) Update c) Config h) Help q) Quit
+ ---------------------------------------------------------------------------
+ Downloader> c
+
+ Data Server:
+ - URL: <https://raw.githubusercontent.com/nltk/nltk_data/gh-pages/index.xml>
+ - 6 Package Collections Available
+ - 107 Individual Packages Available
+
+ Local Machine:
+ - Data directory: /home/tflorac/nltk_data
+
+ Config> d
+ New directory> /usr/local/lib/nltk_data
+
+
+*4. Return to the main menu:*
+
+.. code-block:: shell
+
+ ---------------------------------------------------------------------------
+ s) Show Config u) Set Server URL d) Set Data Dir m) Main Menu
+ ---------------------------------------------------------------------------
+ Config> m
+
+
+*5. Download utilities:*
+
+ punkt
+ Punkt Tokenizer Models
+ stopwords
+ Stopwords Corpus
+
+
+.. code-block:: shell
+
+ ---------------------------------------------------------------------------
+ d) Download l) List u) Update c) Config h) Help q) Quit
+ ---------------------------------------------------------------------------
+ Downloader> d
+ Download which package (l=list; x=cancel)?
+ Identifier> punkt
+ Downloading package punkt to /usr/local/lib/nltk_data...
+ Downloader> d
+ Download which package (l=list; x=cancel)?
+ Identifier> stopwords
+ Downloading package stopwords to /usr/local/lib/nltk_data...
+
+
+.. tip::
+
+ The full list of NTLK Collection can be displayed with the ``l) list`` option.
--- a/src/source/quickstart.rst Fri Apr 27 14:44:33 2018 +0200
+++ b/src/source/quickstart.rst Wed May 16 14:03:44 2018 +0200
@@ -154,8 +154,8 @@
1. The variable **$((INSTALL))** is the path to current folder; it will be replaced automatically by cookiecutter
after application creation
- 2. You will be invited to setup additional services like **Elasticsearch** but you must install them on
- your own.
+ 2. You will be invited to setup additional PyAMS plugins like **Elasticsearch** but you must install related services on
+ your own. See also :ref:`plugins`
.. code-block:: bash