I would prefer not using .pyi. Inline type hints are much more useful, especially for documentation.
Unfortunately, stubgen doesn't seem too successful: neither annotating things with Any, not specifying None return values, nor determinig that constants are str or int, is very useful.

IMO, type hints are useful for documentation purposes.
I would love to use Sphinx's autofunction to generate function signatures in the reference docs; maybe that can be done along with the type annotations?

I would prefer not using .pyi. Inline type hints are much more useful, especially for documentation.

See my quote from @tiran - type hints will be added directly into the Python code .py files after the old Python 2 code has been purged.
For now I'm using the .pyi files as my project is still Python 2.

Unfortunately, stubgen doesn't seem too successful: neither annotating things with Any, not specifying None return values, nor determinig that constants are str or int, is very useful.

Yes, it's a lot of work as stubgen only provides a very basic template. There are other tools which can generate better stubs by using runtime information - it's on my todo list to try them out.

IMO, type hints are useful for documentation purposes.
I would love to use Sphinx's autofunction to generate function signatures in the reference docs; maybe that can be done along with the type annotations?

Yes, I'm already using sphinx-autodoc-typehints, which re-uses the Python type annotation for Sphinx documentation, too.

@pmhahn see PR #522 for a first attempt at adding type hints