Put information about stub files in the documentation

[KRunchPL]

What is the request about

Describing in a documentation what to do, so your module has hints shown by IDE and types checking tools.

Reasoning

I have just started using pyo3 to create a Python package that I can use in my Python application. It took me some time googling on how to make the hints and typing which is a very common need in my opinion. The simple "How to" would be a nice improvement to the documentation and help newbies, especially that even although my code is working I am not sure if I have found the best solution.

Details of proposed solution

There are two issues I have found that are related to this topic:

• [Feature Request] add support for type annotation hints in #[text_signature] macro. #1112
• Feature request: Generate stub files along during compile #510

As far as I understood, the best way right now is to write the *.pyi files manually and just attach it to the package (with maturin it is easy).

I would be glad to help with this part of documentation, but I am not sure if above statement is completely true or we can somehow use comments/docstrings/signatures in rust code to make it happen.

[davidhewitt]

Thanks, some additions to the guide would be very welcome. You're correct that the best solution at the moment is to maintain .pyi files manually. It would be awesome to have #510 implemented some day, however it's a future feature!