Deprecate onbuild images

Add a warning when building an image using "onbuild" tags.
Rework the documentation to make "onbuild" less documented and not the "first
example".

We deprecated onbuild images because too much magic occur with them, and
working with ARG/ENV on onbuild images is complicated.

They will probably be planned for deprecation on docker itself: https://github.com/docker-library/official-images/issues/2076

Dockerfile.onbuild

 ARG FROM
 FROM $FROM
+ONBUILD RUN echo "onbuild images are DEPRECATED, use plain $FROM image instead"
 ONBUILD ARG CW_INSTANCE_NAME
 ONBUILD ENV CW_INSTANCE=${CW_INSTANCE_NAME:-instance}
 ONBUILD USER root

README.rst

@@ -15,7 +15,6 @@ Tags
 Images with cubicweb pre-installed:
 
 * ``latest``, ``3.26``, ``py37-buster-3.26``
-* ``onbuild``, ``3.26-onbuild``, ``py37-buster-3.26-onbuild``
 * ``dev``, ``py37-buster-dev`` (built using latest mercurial changeset)
 * ``3.25``, ``py27-buster-3.25``
 * ``py35-stretch-3.26``
@@ -58,9 +57,8 @@ The image has some expectations:
   set the ``CUBE`` environment variable.
 
 * The default instance name is "instance" and its configuration directory is in
-  /etc/cubicweb.d/instance, this can be changed with the ``CW_INSTANCE``
-  environment variable or via the ``CW_INSTANCE_NAME`` build argument for
-  ``onbuild`` images. Although you shouldn't need to modify this.
+  /etc/cubicweb.d/instance, this can be changed with the ``CW_INSTANCE``.
+  Although you shouldn't need to modify this.
 
 
 How to build an image for a cubicweb application ?
@@ -74,11 +72,37 @@ Here are some hints to make the best choice:
 * Images with cubicweb pre-installed build faster
 * Images without cubicweb pre-installed allow to use your own version of cubicweb
 * ``onbuild`` images are useful when the Dockerfile in versioned in the source
-  tree, except when your cube require a build toolchain to install.
+  tree, except when your cube require a build toolchain to install. However
+  they are DEPRECATED.
+
+Example
+~~~~~~~
+
+For example, given you're in the source tree of `cubicweb-blog`_::
+
+   FROM logilab/cubicweb:3.26
+   USER root
+   COPY . /src
+   RUN pip install -e /src
+   USER cubicweb
+   RUN docker-cubicweb-helper create-instance
+
+
+In case of out-of-source tree or not installing from /src directory, you will
+also have to set the ``CUBE`` environment variable::
+
+   FROM logilab/cubicweb:3.26
+   USER root
+   RUN pip install cubicweb-blog
+   USER cubicweb
+   ENV CUBE=blog
+   RUN docker-cubicweb-helper create-instance
 
 onbuild images
 ~~~~~~~~~~~~~~
 
+.. warning:: A lot of magic happen with onbuild images. They are DEPRECATED.
+
 All images have a ``onbuild`` version by adding the suffix ``-onbuild``.
 The single tag ``onbuild`` is an alias for py37-buster-3.26-onbuild.
 
@@ -102,37 +126,6 @@ In case you don't want a cubicweb version pre-installed and let your own depende
 .. _cubicweb-blog: https://hg.logilab.org/master/cubes/blog
 
 
-other images
-~~~~~~~~~~~~
-
-This is useful for bulding images out of the source tree, or when you require
-additional dependencies to bootstrap the instance.
-
-In this case you have to:
-
-* install your cube and dependencies
-* bootstrap an instance in /etc/cubicweb.d/instance
-
-For example, given you're in the source tree of `cubicweb-blog`_::
-
-   FROM logilab/cubicweb:3.26
-   USER root
-   COPY . /src
-   RUN pip install -e /src
-   USER cubicweb
-   RUN docker-cubicweb-helper create-instance
-
-
-In case of out-of-source tree or not installing from /src directory, you will
-also have to set the ``CUBE`` environment variable::
-
-   FROM logilab/cubicweb:3.26
-   USER root
-   RUN pip install cubicweb-blog
-   USER cubicweb
-   ENV CUBE=blog
-   RUN docker-cubicweb-helper create-instance
-
 How to run resulting images ?
 -----------------------------