WIP-Improved documentation

* Improves documentation by re-arranging its structure and
  introducing full discussion about performance merit of
  intbitset.

Signed-off-by: Samuele Kaplun <samuele.kaplun@cern.ch>
Should I really think about Python 3? This is just an illustration for performance. The user does not really need to re-play them. Indeed it can be enough to drop the `print` statement...