docs: Start of API reference, for emlearn_cnn

jonnor · jonnor · commit bb0fdf980762 · 2025-01-19T13:15:39.000+01:00
diff --git a/docs/api_reference.rst b/docs/api_reference.rst
@@ -0,0 +1,24 @@
+
+.. Places parent toc into the sidebar
+:parenttoc: True
+
+.. title:: API: contents
+
+.. _api_reference:
+
+====================
+API reference
+====================
+
+
+.. toctree::
+   :numbered:
+   :maxdepth: 2
+   :titlesonly:
+
+
+emlearn_cnn
+------------
+
+.. automodule:: emlearn_cnn
+   :members:
diff --git a/docs/conf.py b/docs/conf.py
@@ -17,7 +17,8 @@
 import sys
 import subprocess
 
-sys.path.insert(0, os.path.abspath('..'))
+# Adjust path so we can find the .py files with API documentation
+sys.path.insert(0, os.path.abspath('../stubs'))
 
 # -- Project information -----------------------------------------------------
 
@@ -44,6 +45,7 @@
     'sphinx.ext.mathjax',
     'sphinx.ext.viewcode',
     'sphinx.ext.autodoc',
+    'sphinx_autodoc_typehints',
     'sphinx.ext.doctest',
     'sphinx.ext.coverage',
     'sphinx.ext.autosectionlabel',
@@ -200,15 +202,7 @@
 
 # -- Extension configuration -------------------------------------------------
 
-
-sphinx_gallery_conf = {
-    'examples_dirs': '../examples',   # path to your example scripts
-    'gallery_dirs': 'auto_examples',  # path to where to save gallery generated output
-    'filename_pattern': '/', # execute all .py files, not just those with plot_ prefix
-}
-
-
-
+# -- Intersphinx
 intersphinx_mapping = {
     "emlearn": ("https://emlearn.readthedocs.io/en/latest/", None),
 }
@@ -219,3 +213,9 @@
 # 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
+
+
diff --git a/stubs/emlearn_cnn.py b/stubs/emlearn_cnn.py
@@ -0,0 +1,46 @@
+# Stub file (PEP 484) with API definitions and documentation for native module
+# Is called .py because Sphinx autodoc currently does not support .pyi files
+
+"""
+Convolutional Neural Network module.
+
+Implemented using TinyMaix (https://github.com/sipeed/TinyMaix/).
+
+Note that multiple variants of this module is provided.
+So the import should either be **emlearn_cnn_fp32** (for 32 bit floating point),
+or **emlearn_cnn_int8** (for 8 bit integers, quantized model).
+
+"""
+
+import array
+
+class Model():
+    """A Convolutional Neural Network
+
+    Note: May not be constructed directly. Instead use the new() function.
+    """
+    def run(self, inputs : array.array, outputs: array.array):
+        """
+        Run inference using the model
+
+        :param inputs: the input data
+        :param outputs: where to put model outputs
+        """
+        pass
+
+    def output_dimensions(self) -> tuple[int]:
+        """
+        Get the output dimensions/size of the model
+
+        Useful to know how large an array to pass to run()
+        """
+        pass
+
+def new(model_data : array.array) -> Model:
+    """
+    Construct a new Convolutional Neural Network
+
+    :param model_data: The model definition (.TMDL file, as bytes).
+    """
+    pass
+
