--- a/README	Wed Apr 30 12:09:35 2014 +0200
+++ b/README	Wed Apr 30 11:21:51 2014 +0200
@@ -1,70 +1,68 @@
 README for apycot
 =================
 
-project home page: http://www.cubicweb.org/project/apycot
-mercurial repository: http://www.logilab.org/src/cubes/apycot
+Apycot_ is an Automated Python Code Testing platform built on narval_
+and cubicweb_.
+
+.. _Apycot: http://www.cubicweb.org/project/apycot
+.. _narval: http://www.cubicweb.org/project/narval
+.. _cubicweb: http://www.cubicweb.org/project/cubicweb
 
 Installation and configuration
 ``````````````````````````````
 
+Apycot_ is based on narval_, so make sure you have a working narval_
+setup. Please refer to narval's documentation for help on installing a
+narval setup.
+
+Once you have a properly functionning narval setup, you have to
+install Apycot elements on both the website part and the narval-bot
+side.
+
 On the web/data server host
 ---------------------------
 
-* Install cubicweb and the cubicweb-apycot packages (more info in the
-  `cubicweb book`_). Notice that the apycot cube may be integrated with
-  `tracker`_ based instances.
-
-* Set pyro-server=yes in your instance's configuration file
+* Install the `cubicweb-apycot` package (more info in the
+  `cubicweb book`_).
 
-* Create environment and test configuration entities through the web
-  ui of your instance(s) to describe what to test. (See `More
-  documentation`_)
-
-* Modify password for the narval user for better security
+* Modify password for the narval user for better security.
 
 
 On the bot host
 ---------------
 
-* Install the narval-apycot package.
+* Install the `narval-apycot` package.
 
-* edit /etc/narval.ini, or ~/etc/narval.ini when running
-  code from hg, to adjust the bot configuration. You can also generate
-  a stub configuration file using `narval rcfile > /etc/narval.ini`
+* Edit `/etc/narval/narval.ini`, is neccessary (or `~/etc/narval.ini`
+  when running code from hg) to adjust the bot configuration. You can
+  also generate a stub configuration file using `narval rcfile >
+  /etc/narval/narval.ini`.
 
-* If using different user/password for the apycot bot in cubicweb
-  instances than default ones (higly recommended), indicate connection
-  information for each instance in a /etc/narval-cw-sources.ini file.
-  for instance ::
+* Indicate the connection informations for each instance in the
+  `/etc/narval/narval-cw-sources.ini` file (makesure this file is not
+  world readable), for instance::
 
       [cwo]
-      user=narval
-      password=apycot
+      url=https://www.cubicweb.org/
+      token_id=The Token Name
+      secret=<generated secret>
 
       [elo]
-      user=narval
-      password=apycot
+      url=https://www.logilab.org/
+      token_id=The Other Token Name
+      secret=<generated secret>
 
-  where each section is the pyro name of an instance. You should
-  restrict read perms to this file aggressively.
+  where each section is the configuration for a cubicweb
+  application.
 
-* for those running from source, `narval/bin/narval` should be
-  in PATH
+* For those running from source, `narval/bin/narval` **must** be in
+  `PATH` (since the `narval` daemon spawns subprocess via the `narval`
+  command).
 
 .. _`cubicweb book`: http://www.cubicweb.org/
-.. _`tracker`: http://www.cubicweb.org/project/cubicweb-tracker
 
-Once both sides are running, check both are properly registered in the
-pyro name server by running
-
-  pyro-nsc listall
-
-You should see your instance as 'cubicweb:...' and the bot as 'narval:...'.
- or in /etc (narval from debian package). This
-allows arbitrary password (it's recommended to change the default one), and
-also have the nice effect that when your bot will be (re)started, it will connect
-to each instance listed in this file to search for pending plans.
-
+You may check the bot can connect to the cubicweb instances by
+watching the narval bot's logs (usually in `/var/log/narval/`).
 
 
 More documentation
@@ -72,7 +70,12 @@
 
 Beside low-level installation (described here), all the documentation to setup your
 continuous integration environment is available online through your instance at
-http://<your instance url>/doc/apycot
+`http://<your instance url>/doc/apycot`
+
+You should read this documentation in order to be able to create all
+the required objects to build your own testing and continuous
+integration platform.
+
 
 Feedbacks, bug reports
 ``````````````````````

--- a/wdoc/apycot_links_en.rst	Wed Apr 30 12:09:35 2014 +0200
+++ /dev/null	Thu Jan 01 00:00:00 1970 +0000
@@ -1,18 +0,0 @@
-Abbreviation
-------------
-
-:CW: Cubicweb
-:CI: Continuous Integration
-:VCS: Version Control System
-
-.. _`automate this`: `doc/apycpt_automation
-.. _`vcsfile cube`: doc/vcsfile
-.. _`all available variables`: apycotdoc
-
-.. _apycot: http://www.logilab.org/projects/apycot
-.. _devtools: http://www.logilab.org/projects/devtools
-.. _pylint: http://www.logilab.org/projects/pylint
-.. _mxtidy: http://www.egenix.com
-.. _lxml: http://codespeak.net/lxml/ 
-.. _Zope: http://www.zope.org
-.. _docutils: http://docutils.sourceforge.net

--- a/wdoc/apycot_quick_start_en.rst	Wed Apr 30 12:09:35 2014 +0200
+++ b/wdoc/apycot_quick_start_en.rst	Wed Apr 30 11:21:51 2014 +0200
@@ -1,5 +1,5 @@
 ====================
- Apycot Quick Start 
+ Apycot Quick Start
 ====================
 
 --------
@@ -11,7 +11,7 @@
 application extending the Narval framework. It adds the notion of preprocessors
 and checkers to Narval. The preprocessors are used mainly to checkout
 version-controlled repositories and setup a test environment while the checkers
-correspond to specific checks (pycoverage, pytest, pylint...). 
+correspond to specific checks (pycoverage, pytest, pylint...).
 
 Other major differences with respect to Narval include the use of TestExecution
 and CheckResults instead of Plans to store the results and the organisation of
@@ -51,11 +51,11 @@
 ============
 
 In addition to what is described in the Narval documentation, you need to install
-the additional ``narval-apycot`` package (it contains the additional checkers and 
+the additional ``narval-apycot`` package (it contains the additional checkers and
 preprocessors used by apycot).
 
 .. sourcecode:: bash
-  
+
   apt-get install narval-bot narval-apycot
 
 Configuration
@@ -73,8 +73,8 @@
 To install a complete Apycot environment, you need to install the following packages:
 
 .. sourcecode:: bash
-  
-  apt-get install cubicweb-apycot cubicweb-ctl 
+
+  apt-get install cubicweb-apycot cubicweb-ctl
 
 Creating an Apycot instance
 ===========================
@@ -83,14 +83,6 @@
 
   cubicweb-ctl create apycot myapycot
 
-As explained in the Narval documentation, you need to fill-in the ``base-url``
-before creating the database as the bot uses this address to connect to the web
-application. This file is usually available in
-``[~]/etc/cubicweb.d/<instance-name>``.
-
-.. sourcecode:: bash
-
-  cubicweb-ctl db-create myapycot
 
 You can then launch the CubicWeb instance:
 
@@ -98,8 +90,8 @@
 
   cubicweb-ctl start -D myapycot
 
-Make sure the bot manages to connect to the instance by looking at the logs in `/var/log/narval/narval.log`. If you see something like :: 
-  
+Make sure the bot manages to connect to the instance by looking at the logs in `/var/log/narval/narval.log`. If you see something like::
+
   2014-01-15 20:20:40 - (narval.bot) INFO: get pending plan from narval
   2014-01-15 20:20:40 - (requests.packages.urllib3.connectionpool) INFO: Starting new HTTP connection (1): crater2.logilab.fr
 
@@ -134,7 +126,7 @@
 =============================
 
 We first describe the entity types added by Apycot and then provide a complete
-setup procedure. 
+setup procedure.
 
 Creating a project environment (ProjectEnvironment)
 ---------------------------------------------------
@@ -167,7 +159,7 @@
 Usually, when checkers or preprocessors fail, or crash, some of these variables
 are incorrect or missing.
 
-Creating a test configuration (TestConfig) 
+Creating a test configuration (TestConfig)
 ------------------------------------------
 
 Usually, a recipe requires at least a TestConfig. This configuration
@@ -186,7 +178,7 @@
 - the recipe associated to the TestConfig. This recipe will be launched
   by the narval instance when this configuration will be used.
 - the "refinement of" specifies the parent TestConfig. The current TestConfig
-  will inherit all the attributes and variables from the parent TestConfig. 
+  will inherit all the attributes and variables from the parent TestConfig.
 
 To run tests you must link the TestConfig to a ProjectEnvironment and specify a
 recipe. Make sure the options necessary for each checker and preprocessor are
@@ -201,21 +193,21 @@
 To setup a Repository, you need to specify:
 
 - the type of the VCS handling the Repository;
-- the path to the Repository. 
+- the path to the Repository.
 
 Make sure the Repository can be accessed by both the Apycot Web application and
 the Narval bot instance.
 
 In the "files" tab you can find all the files in the current revision, whereas
 in the "revisions" tabs you have a table with all revisions known to the
-Repository. 
+Repository.
 
 Full setup procedure
 --------------------
 
 Make sure the cubicweb instance running Apycot and the Narval bot instance are
 both installed, configured (as shown above and in the Narval documentation) and
-able to communicate (see their respective install procedures). 
+able to communicate (see their respective install procedures).
 
 1. Setup a Repository for the project
 2. Create a TestConfig for each recipe you want to be able to run.
@@ -233,23 +225,6 @@
 Troubleshooting
 ---------------
 
-The Narval bot successfully retrieves the plan and runs the checks, but the
-reports are never transmitted to the Web application:
-
-- The `base-url` is used by the user to connect to the Web application, but
-  also by the Narval bot to transmit its results back to the application.
-  Hence, the Narval bot must be able to connect to the Web application using the
-  base-url provided in the `all-in-one.conf` file. A similar problem arises
-  when the cwuri of the TestExecutions, TestConfigs and Checkresultsare wrong
-  or outdated: the narvalbot uses these cwuri to connect to the instance. You
-  should check these values and make sure there are up to date. 
-
-.. sourcecode:: python 
-
-  >>> for ent in rql('Any X WHERE X cwuri LIKE "None%"').entities(): 
-          ent.cw_set(cwuri=ent.cwuri.replace('None',
-                                        'http://crater2.logilab.fr:10003/'))
-
 The Narval bot never gets the plan and the interval between the bot's polls is
 too long:
 
@@ -258,14 +233,14 @@
 
   [narval]
   url=http://instance-name.fr:10003/
-  user=narval
-  password=narval0
-  poll-delay=5 
+  token_id=token name
+  secret=generated secret
+  poll-delay=5
 
 The checkers crash but the project tests are fine, the project is not installed
 correctly:
 
 - make sure no configuration and environment variables are missing or wrongly
-  set. 
+  set.
 - check the paths used by Narval bot are writable and free space is available
   on the disk.