DOC: clean-up docstrings of option functions
Some clean-up after my last additions to api.rst to get rid off all warnings:
- some clean up of api.rst itself
- some clean-up of the docstrings of the option functions so they render nicely with sphinx
