Fixes for the reported sphinx errors 

Just a resync PR before Basic Usage uploads
we had it and sphinx was complaining for lacking flesh... this this PR.
I think it is more of incomplete, rather than broken; would you agree with that statement?
if so, I'd suggest to keep it and if we cannot improve it upon 1.0 docs release, just defer it, no?