Create package for stub files, use sphinx-autoapi for processing.

.gitignore

@@ -8,3 +8,5 @@ venv/
 .ipynb_checkpoints/
 __pycache__/
 .mpy_ld_cache/
+
+**/dist

doc/developing-c-modules.md

@@ -27,8 +27,8 @@ Standard external C modules build.
 ! Windows only supported using Windows Subsystem for Linux?
 - API refererence documentation.
 Using stub files sphinx with sphinx-autodoc-typehints
-- ?? How to use the stubs for typechecking, like micropython stubs
-
+- stubs can be installed from a local clone using  : `pip install ./stubs`
+  or from the github repository using : `pip install git+https://github.com/emlearn/emlearn-micropython#subdirectory=stubs`
 ## Examples
 
 - emlearn-micropython, https://github.com/emlearn/emlearn-micropython/

docs/api_reference.rst

@@ -21,52 +21,52 @@ API reference
 emlearn_trees - Decision tree ensembles
 ----------------------------------------------------
 
-.. automodule:: emlearn_trees
+.. autoapimodule:: emlearn_trees
    :members:
 
 .. _emlearn_linreg:
 emlearn_linreg - Linear regression
 ----------------------------------------------------
 
-.. automodule:: emlearn_linreg
+.. autoapimodule:: emlearn_linreg
    :members:
 
 .. _emlearn_cnn:
 emlearn_cnn - Convolutional Neural Networks
 ----------------------------------------------------------
 
-.. automodule:: emlearn_cnn
+.. autoapimodule:: emlearn_cnn
    :members:
 
 
 .. _emlearn_neighbors:
 emlearn_neighbors - K Nearest Neighbors (KNN)
 ---------------------------------------------------------
 
-.. automodule:: emlearn_neighbors
+.. autoapimodule:: emlearn_neighbors
    :members:
 
 
 .. _emlearn_fft:
 emlearn_fft - Fast Fourier Transform
 ---------------------------------------------------------
 
-.. automodule:: emlearn_fft
+.. autoapimodule:: emlearn_fft
    :members:
 
 
 .. _emlearn_iir:
 emlearn_iir - Infinite Impulse Reponse filters
 ---------------------------------------------------------
 
-.. automodule:: emlearn_iir
+.. autoapimodule:: emlearn_iir
    :members:
 
 
 .. _emlearn_arrayutils:
 emlearn_arrayutils - Efficient utilities for array.array
 ---------------------------------------------------------
 
-.. automodule:: emlearn_arrayutils
+.. autoapimodule:: emlearn_arrayutils
    :members:
 

docs/conf.py

@@ -17,9 +17,6 @@
 import sys
 import subprocess
 
-# Adjust path so we can find the .py files with API documentation
-sys.path.insert(0, os.path.abspath('../stubs'))
-
 # -- Project information -----------------------------------------------------
 
 project = 'emlearn-micropython'
@@ -44,8 +41,7 @@
 extensions = [
     'sphinx.ext.mathjax',
     'sphinx.ext.viewcode',
-    'sphinx.ext.autodoc',
-    'sphinx_autodoc_typehints',
+    'autoapi.extension',
     'sphinx.ext.doctest',
     'sphinx.ext.coverage',
     'sphinx.ext.autosectionlabel',
@@ -202,6 +198,22 @@
 
 # -- Extension configuration -------------------------------------------------
 
+# -- AutoAPI
+autoapi_dirs = [os.path.abspath('../stubs')]
+autoapi_file_patterns = ['*.pyi']
+autoapi_type = 'python'
+autoapi_member_order = 'groupwise'
+autoapi_generate_api_docs = False
+autoapi_keep_files = False
+autoapi_add_toctree_entry = False
+autoapi_options = [
+    'members',
+    'undoc-members',
+    'show-inheritance',
+    'show-module-summary',
+    'special-members',
+]
+
 # -- Intersphinx
 intersphinx_mapping = {
     "emlearn": ("https://emlearn.readthedocs.io/en/latest/", None),
@@ -213,9 +225,7 @@
 # https://www.sphinx-doc.org/en/master/usage/extensions/intersphinx.html#confval-intersphinx_disabled_reftypes
 intersphinx_disabled_reftypes = ["*"]
 
-# -- autodoc typehints
-always_document_param_types = True
-typehints_fully_qualified = True
-always_use_bars_union = True
+# -- type display preferences
+python_use_unqualified_type_names = True
 
 

requirements.dev.txt

@@ -1,4 +1,5 @@
 sphinx>=4.0.0
+sphinx-autoapi>=3.0.0
 recommonmark>=0.6.0
 sphinx_rtd_theme>=0.5.2
 sphinx-gallery>=0.10.1

stubs/pyproject.toml

@@ -0,0 +1,22 @@
+[build-system]
+requires = ["hatchling>=1.24"]
+build-backend = "hatchling.build"
+
+[project]
+name = "emlearn-micropython-stubs"
+version = "0.11.1"
+description = "Stub-only package for emlearn MicroPython modules"
+requires-python = ">=3.8"
+license = { text = "MIT" }
+authors = [
+  { name = "Jon Nordby" }
+]
+classifiers = [
+  "Programming Language :: Python :: 3",
+  "Typing :: Stubs Only",
+]
+
+[tool.hatch.build.targets.wheel]
+include = [
+  "*.pyi",
+]