Ship type hinting stub files

[lazka]

stubgen gives a good overview for py3 already: https://bpaste.net/show/e0edfe462061

• can we share things for py2/py3?
• how can we integrate it in the test suite to check if all public API (minus deprecated things) is covered and things don't bitrot?
• How does pycharm handle documentation in sub files?

Ideally we'd want that for pygobject as well, but pycairo seems like a good start for testing things out.

[lazka]

"PEP 561 -- Distributing and Packaging Type Information" https://www.python.org/dev/peps/pep-0561/

[lazka]

We could also try supporting "__signature__" on the C level first, so that stubgen has a more complete output..

[lazka]

stubgen ignores them, so let's just add .pyi and take it from there..