PyQIR generator documentation is incomplete

[bamarsha]

The documentation at https://qir-alliance.github.io/pyqir/api-reference/generator.html is missing parameters, types and docstrings. This is likely because Sphinx can't read .pyi files for autodoc sections: sphinx-doc/sphinx#7630

[LaurentAjdnik]

I looked around but indeed found no way to generate docs from .pyi files with Sphinx.

But I feel like this is possible from "docstrings" included in the Rust source itself.

The Fastobo project seems to have achieved this.

For instance, with the load_graph() function:

• Rust source with docstring
• Doc generation
• Resulting doc

Their conf.py file is here.

[idavis]

@SamarSha @cgranade - What @LaurentAjdnik shows here is pretty interesting. Do you have any thoughts on this? Might be a better option than hoping sphinx adds .pyi support.

[bamarsha]

Rust doc comments will get attached as Python docstrings, but I think we'll still need to duplicate the types in both the docstring and the .pyi file. I'm also not sure how it will work when referring to Mypy type aliases defined in Python.