Very minor refactoring and edits to code comments
Just some miscellaneous improvements on things that tripped me up a bit.

@Garrett-R The changes to the docs and conf.py seem good to me.

For the clean-up in the code, I will let someone else review, as I am not familiar with that part of the code.

By the way, to make our (easier to review) and your (easier to update, quicker merged) life easier, it is often times a good approach to do separate PRs for clearly separate things (here it is not yet a big problem, as it are not that much of lines that are changed, but just giving the tip for possible future contributions)
 @jorisvandenbossche, right, good call.  I'll do that next time.
 merged via https://github.com/pydata/pandas/commit/a7437430b5cb62e49a79b64d18eccfb2b4d6367f

thanks!
