improve docs
improve docs

* add cross-ref
* fix typo: its -> it's
* cancel a note block, which should continue into the next paragraph

--HG--
branch : trunk

moreati/pylons,Pylons/pylons,moreati/pylons,Pylons/pylons,moreati/pylons,Pylons/pylons