Add `.pyi` Stub Files

[ax3l]

Automate the generation of stub files with CI tools.

Sphinx

• https://pybind11.readthedocs.io/en/stable/advanced/misc.html#generating-documentation-using-sphinx
• Use PEP 484 stub files when documenting native extensions with autodoc sphinx-doc/sphinx#7630
• https://www.sphinx-doc.org/en/master/usage/extensions/autodoc.html#confval-autodoc_docstring_signature

Automation

• https://github.com/marketplace/actions/add-commit
• https://github.com/stefanzweifel/git-auto-commit-action

Generators

pybind11-stubgen

https://github.com/sizmailov/pybind11-stubgen

pybind11-stubgen amrex
pybind11-stubgen amrex.space1d
pybind11-stubgen amrex.space2d
pybind11-stubgen amrex.space3d

Creates files in stubs/. Does not automatically go recursive?

Pro:

• doc strings preserved!

Cons:

• Quote sensitive, errors on encountered C++ types in signatures (for non-bound types?).
  • --ignore-all-errors helps.
  • actually a good diagnostics to fix unbound types and init-order issues.

MyPy

https://mypy.readthedocs.io/en/stable/stubgen.html
https://github.com/MikePopoloski/pyslang/issues/96

stubgen -p amrex
stubgen -p amrex.space2d
stubgen -p amrex.space3d

Processed 5 modules
Generated files under out/amrex/

Pro:

• no errors

Con:

• no doc strings [FEAT] Generate docstrings that are compatible with Sphinx and stubgen pybind/pybind11#2619

nanobind-stubgen

After #127 -> https://github.com/cansik/nanobind-stubgen

• nanobind-stubgen - Generate python stub files for code completion wjakob/nanobind#163
• Generate documentation and stub file for nanobind Python module wjakob/nanobind#171

Other

• creating stub pyi files automatically from pybind projects pybind/pybind11#2350 (comment)