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>
You can use http://sphinx-doc.org/markup/para.html#directive-note