--- a/doc/book/admin/cubicweb-ctl.rst	Mon Sep 26 09:57:15 2016 +0200
+++ b/doc/book/admin/cubicweb-ctl.rst	Mon Sep 26 10:32:44 2016 +0200
@@ -34,12 +34,9 @@
 
 Create your new cube cube ::
 
-   cubicweb-ctl newcube
+   cubicweb-ctl newcube -d <target directory>
 
-This will create a new cube in
-``/path/to/grshell-cubicweb/cubes/<mycube>`` for a Mercurial
-installation, or in ``/usr/share/cubicweb/cubes`` for a debian
-packages installation.
+This will create a new cube ``<target directory>``.
 
 Create an instance
 -------------------

--- a/doc/book/devrepo/cubes/cc-newcube.rst	Mon Sep 26 09:57:15 2016 +0200
+++ b/doc/book/devrepo/cubes/cc-newcube.rst	Mon Sep 26 10:32:44 2016 +0200
@@ -3,12 +3,12 @@
 
 Let's start by creating the cube environment in which we will develop ::
 
-  cd ~/cubes
+  cd ~/myproject
   # use cubicweb-ctl to generate a template for the cube
   # will ask some questions, most with nice default
   cubicweb-ctl newcube mycube
   # makes the cube source code managed by mercurial
-  cd mycube
+  cd cubicweb-mycube
   hg init
   hg add .
   hg ci
@@ -22,21 +22,3 @@
 This variable is used for the instance packaging (dependencies handled
 by system utility tools such as APT) and to find used cubes when the
 database for the instance is created.
-
-On a Unix system, the available cubes are usually stored in the
-directory :file:`/usr/share/cubicweb/cubes`. If you are using the
-cubicweb mercurial repository (:ref:`SourceInstallation`), the cubes
-are searched in the directory
-:file:`/path/to/cubicweb_toplevel/cubes`. In this configuration
-cubicweb itself ought to be located at
-:file:`/path/to/cubicweb_toplevel/cubicweb`.
-
-.. note::
-
-    Please note that if you do not wish to use default directory for your cubes
-    library, you should set the :envvar:`CW_CUBES_PATH` environment variable to
-    add extra directories where cubes will be search, and you'll then have to use
-    the option `--directory` to specify where you would like to place the source
-    code of your cube:
-
-    ``cubicweb-ctl newcube --directory=/path/to/cubes/library mycube``

--- a/doc/book/devrepo/cubes/layout.rst	Mon Sep 26 09:57:15 2016 +0200
+++ b/doc/book/devrepo/cubes/layout.rst	Mon Sep 26 10:32:44 2016 +0200
@@ -6,17 +6,46 @@
 Standard structure for a cube
 -----------------------------
 
-A cube is structured as follows:
+A cube named "mycube" is Python package "cubicweb-mycube" structured as
+follows:
 
 ::
 
-  mycube/
+  cubicweb-mycube/
   |
-  |-- data/
-  |   |-- cubes.mycube.css
-  |   |-- cubes.mycube.js
-  |   `-- external_resources
-  |
+  |-- cubicweb_mycube/
+  |   |
+  |   |-- data/
+  |   |   |-- cubes.mycube.css
+  |   |   |-- cubes.mycube.js
+  |   |   `-- external_resources
+  |   |
+  |   |
+  |   |-- entities.py
+  |   |
+  |   |-- i18n/
+  |   |   |-- en.po
+  |   |   |-- es.po
+  |   |   `-- fr.po
+  |   |
+  |   |-- __init__.py
+  |   |
+  |   |
+  |   |-- migration/
+  |   |   |-- postcreate.py
+  |   |   `-- precreate.py
+  |   |
+  |   |-- __pkginfo__.py
+  |   |
+  |   |-- schema.py
+  |   |
+  |   |
+  |   |-- site_cubicweb.py
+  |   |
+  |   |-- hooks.py
+  |   |
+  |   |
+  |   `-- views.py
   |-- debian/
   |   |-- changelog
   |   |-- compat
@@ -24,56 +53,32 @@
   |   |-- copyright
   |   |-- cubicweb-mycube.prerm
   |   `-- rules
-  |
-  |-- entities.py
-  |
-  |-- i18n/
-  |   |-- en.po
-  |   |-- es.po
-  |   `-- fr.po
-  |
-  |-- __init__.py
-  |
   |-- MANIFEST.in
-  |
-  |-- migration/
-  |   |-- postcreate.py
-  |   `-- precreate.py
-  |
-  |-- __pkginfo__.py
-  |
-  |-- schema.py
-  |
   |-- setup.py
-  |
-  |-- site_cubicweb.py
-  |
-  |-- hooks.py
-  |
-  |-- test/
-  |   |-- data/
-  |   |   `-- bootstrap_cubes
-  |   |-- pytestconf.py
-  |   |-- realdb_test_mycube.py
-  |   `-- test_mycube.py
-  |
-  `-- views.py
+  `-- test/
+      |-- data/
+      |   `-- bootstrap_cubes
+      |-- pytestconf.py
+      |-- realdb_test_mycube.py
+      `-- test_mycube.py
 
 
-We can use subpackages instead of python modules for ``views.py``, ``entities.py``,
+We can use subpackages instead of Python modules for ``views.py``, ``entities.py``,
 ``schema.py`` or ``hooks.py``. For example, we could have:
 
 ::
 
-  mycube/
+  cubicweb-mycube/
   |
-  |-- entities.py
-  |-- hooks.py
-  `-- views/
-      |-- __init__.py
-      |-- forms.py
-      |-- primary.py
-      `-- widgets.py
+  |-- cubicweb_mycube/
+  |   |
+      |-- entities.py
+  .   |-- hooks.py
+  .   `-- views/
+  .       |-- __init__.py
+          |-- forms.py
+          |-- primary.py
+          `-- widgets.py
 
 
 where :
@@ -127,6 +132,27 @@
 something defined in the other's schema; on database creation, on something
 created by the other's postcreate, and so on.
 
+The :file:`setup.py` file
+-------------------------
+
+This is standard setuptools based setup module which reads most of its data
+from :file:`__pkginfo__.py`. In the ``setup`` function call, it should also
+include an entry point definition under the ``cubicweb.cubes`` group so that
+CubicWeb can discover cubes (in particular their custom ``cubicweb-ctl``
+commands):
+
+::
+
+    setup(
+      # ...
+      entry_points={
+          'cubicweb.cubes': [
+              'mycube=cubicweb_mycube',
+          ],
+      },
+      # ...
+    )
+
 
 :file:`migration/precreate.py` and :file:`migration/postcreate.py`
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~