A question/comment:

In this case (and there are probably other cases like it) - it seems to me that the docstring (in os.py) and the docs (in os.rst) are similar enough that the docstring from the code could be included in the docs (using Sphinx's autodoc).

What is the preferred way? Is there a reason to have it the way it is? I notice the .rst docs have some formatting applied, is it considered not OK to put formatting in docstrings?