Missing documentation about multiple inheritance

[Benoît Bryon]

As of version 1.6.2 (as of 2012-10-16, it also affects
development branches), the only reference to multiple
inheritance in documentation seems to be in "Multiple
configuration files" section. See :

* https://github.com/buildout/buildout/blob/1.6.2/src/zc/buildout/buildout.txt#L1317
* https://github.com/buildout/buildout/blob/1.6.2/src/zc/buildout/buildout.txt#L1384

The example deals with a buildout.cfg file which extends
b1.cfg, b2.cfg and b3.cfg.

The option "op2" in "debug" section is defined in both `b1.cfg
<https://github.com/buildout/buildout/blob/1.6.2/src/zc/buildout/buildout.txt#L1330>`_
and `b2.cfg
<https://github.com/buildout/buildout/blob/1.6.2/src/zc/buildout/buildout.txt#L1339>`_.
As a result, `op2 is assigned the value set in b2.cfg which
overrides the value set in b1.cfg
<https://github.com/buildout/buildout/blob/1.6.2/src/zc/buildout/buildout.txt#L1376>`_.

I feel the current example doesn't explain the multiple
inheritance feature:

* what is multiple inheritance meant for? What are typical
  use cases?
* why do op2 only get the value defined in b2.cfg? What is
  the underlying rule?
* which rules are applied when we use "+=" and "-=" operators
  on bases (i.e. what if in b3.cfg we got ``op2 += b3`` and/or
  ``op2 -= b2``).

.. note::

   This ticket is a counterpart of
   https://bugs.launchpad.net/zc.buildout/+bug/1060236 :

   * this ticket is about documenting current feature and
     implementation.
   * https://bugs.launchpad.net/zc.buildout/+bug/1060236 asks
     whether current implementation is bogus and proposes some
     changes.

   So, resolving this ticket may result in #1060236 being marked
   as "wontfix" or being confirmed.

[Benoît Bryon (benoit.bryon)]

In https://bugs.launchpad.net/zc.buildout/+bug/1060236,
Encolpe Degoute (encolpe) wrote on 2012-10-12:

> The documentation is not clear about that but there's no bug there.
>
> You can see how to you can use extends and += look at this package:
> https://github.com/collective/zopeskel.unis

As an example, see https://github.com/collective/zopeskel.unis/blob/master/zopeskel/unis/templates/unis_plone4_buildout/profiles/standalone.cfg_tmpl and its bases.

[Benoît Bryon (benoit.bryon)]

I started a section "Multiple inheritance" in a fork of zc.buildout repository. See:

* Diff: https://github.com/benoitbryon/buildout/compare/buildout:1.6.x...benoitbryon:1067259-multiple-inheritance-documentation

* New section about multiple inheritance: https://github.com/benoitbryon/buildout/blob/1067259-multiple-inheritance-documentation/src/zc/buildout/buildout.txt#L1395

@encolpe: does the example in the branch match zopeskel/unis pattern? Else, what are the differences?

May someone help me update the documentation? Right now, I'm not sure I understood well the multiple inheritance feature (and its implementation).

.. note::

   Currently, changes break other doctests because they are based on the
   example in "Multiple configuration files" section. I guess we will be able to
   restore the broken tests quite easily, once the chapter about multiple
   inheritance is ok.

[Benoît Bryon (benoit.bryon)]

Just to highlight what I haven't figured out yet about current feature:
https://github.com/benoitbryon/buildout/blob/1067259-multiple-inheritance-documentation/src/zc/buildout/buildout.txt#L1565