Docs for Python bindings

[fjarri]

Since pyO3 does not create any actual Python code, we need to just write sphinx docs with hardcoded API. Ideally if it has some doctests that are run automatically.

[fjarri]

Documentation added in commit 702d2ec, need to publish it on RTD.

[fjarri]

Currently any API change requires changing .pyi and the docs too. Need to investigate if it is possible to avoid duplication. In particular:

• if Sphinx can pick up docstrings directly from the built library (so we only need to write them in the Rust part of the bindings)
• if Mypy can pick up typehints directly from the built library

Perhaps we can write a thin Python wrapper instead and store all the docs and typehints there. This way we can enable optional parameters too.

[fjarri]

Update:

• mypy has stubgen that does a pretty good job of generating the .pyi file automatically. How should we introduce it into the build procedure? Also, there's a chance pyo3 will start doing that, see Feature request: Generate stub files along during compile PyO3/pyo3#510
• pyo3 picks up docstrings and puts them into a __doc__ attribute. But: Sphinx still cannot pick up the signatures automatically; one could use [pyo3(text_signature = (...))] attribute (it would be a duplication still, but at least this attribute is right next to the actual function definition), but it currently does not support typehints. See [Feature Request] add support for type annotation hints in #[text_signature] macro. PyO3/pyo3#1112

[fjarri]

Took another attempt at keeping documentations as docstrings in Rust. While the type annotations issue can be worked around by using explicit parameter descriptors (:type:, :rtype:), there are more problems with Sphinx:

• sometimes what's defined in #[text_signature] isn't picked up by Sphinx (even though everything seems fine if one calls help() on the method in REPL). I couldn't figure out what exactly leads to that.
• Sphinx can't pick up the signature of the constructor defined this way

[fjarri]

Also partially blocked by PyO3/pyo3#2016