First documentation of the light API (#44)

* documentation

* remove rstcheck, too many bugs

* add missing link

* fix unit test

* fix documentation

* unstable

* windows

* update titles

* minorchanges

CHANGELOGS.rst

@@ -1,7 +1,7 @@
 Change Logs
 ===========
 
-0.2.0
+0.1.2
 +++++
 
 * :pr:`42`: first sketch for a very simple API to create onnx graph in one or two lines

README.rst

@@ -2,7 +2,7 @@
 .. image:: https://github.com/sdpython/onnx-array-api/raw/main/_doc/_static/logo.png
     :width: 120
 
-onnx-array-api: (Numpy) Array API for ONNX
+onnx-array-api: APIs to create ONNX Graphs
 ==========================================
 
 .. image:: https://dev.azure.com/xavierdupre3/onnx-array-api/_apis/build/status/sdpython.onnx-array-api
@@ -29,7 +29,9 @@ onnx-array-api: (Numpy) Array API for ONNX
 .. image:: https://codecov.io/gh/sdpython/onnx-array-api/branch/main/graph/badge.svg?token=Wb9ZGDta8J 
     :target: https://codecov.io/gh/sdpython/onnx-array-api
 
-**onnx-array-api** implements a numpy API for ONNX.
+**onnx-array-api** implements APIs to create custom ONNX graphs.
+The objective is to speed up the implementation of converter libraries.
+The first one matches **numpy API**.
 It gives the user the ability to convert functions written
 following the numpy API to convert that function into ONNX as
 well as to execute it.
@@ -111,6 +113,31 @@ It supports eager mode as well:
     l2_loss=[0.002]
     [0.042]
 
+The second API ir **Light API** tends to do every thing in one line.
+The euclidean distance looks like the following:
+
+::
+
+    import numpy as np
+    from onnx_array_api.light_api import start
+    from onnx_array_api.plotting.text_plot import onnx_simple_text_plot
+
+    model = (
+        start()
+        .vin("X")
+        .vin("Y")
+        .bring("X", "Y")
+        .Sub()
+        .rename("dxy")
+        .cst(np.array([2], dtype=np.int64), "two")
+        .bring("dxy", "two")
+        .Pow()
+        .ReduceSum()
+        .rename("Z")
+        .vout()
+        .to_onnx()
+    )    
+
 The library is released on
 `pypi/onnx-array-api <https://pypi.org/project/onnx-array-api/>`_
 and its documentation is published at

_doc/api/docs.rst

@@ -0,0 +1,7 @@
+validation.docs
+===============
+
+make_euclidean
+++++++++++++++
+
+.. autofunction:: onnx_array_api.validation.docs.make_euclidean

_doc/api/index.rst

@@ -22,3 +22,4 @@ API
     tools
     profiling
     f8
+    docs

_doc/api/light_api.rst

@@ -24,9 +24,11 @@ Var
 
 .. autoclass:: onnx_array_api.light_api.Var
     :members:
+    :inherited-members:
 
 Vars
 ====
 
 .. autoclass:: onnx_array_api.light_api.Vars
     :members:
+    :inherited-members:

_doc/conf.py

@@ -114,21 +114,34 @@
         "https://data-apis.org/array-api/",
         ("2022.12/API_specification/generated/array_api.{0}.html", 1),
     ),
+    "ast": "https://docs.python.org/3/library/ast.html",
     "cProfile.Profile": "https://docs.python.org/3/library/profile.html#profile.Profile",
     "DOT": "https://graphviz.org/doc/info/lang.html",
+    "inner API": "https://onnx.ai/onnx/intro/python.html",
     "JIT": "https://en.wikipedia.org/wiki/Just-in-time_compilation",
     "onnx": "https://onnx.ai/onnx/",
+    "onnx.helper": "https://onnx.ai/onnx/api/helper.html",
     "ONNX": "https://onnx.ai/",
+    "ONNX Operators": "https://onnx.ai/onnx/operators/",
     "onnxruntime": "https://onnxruntime.ai/",
+    "onnxruntime-training": "https://onnxruntime.ai/docs/get-started/training-on-device.html",
     "numpy": "https://numpy.org/",
     "numba": "https://numba.pydata.org/",
     "onnx-array-api": ("https://sdpython.github.io/doc/onnx-array-api/dev/"),
+    "onnxscript": "https://github.com/microsoft/onnxscript",
     "pyinstrument": "https://github.com/joerick/pyinstrument",
     "python": "https://www.python.org/",
+    "pytorch": "https://pytorch.org/",
+    "reverse Polish notation": "https://en.wikipedia.org/wiki/Reverse_Polish_notation",
     "scikit-learn": "https://scikit-learn.org/stable/",
     "scipy": "https://scipy.org/",
+    "sklearn-onnx": "https://onnx.ai/sklearn-onnx/",
+    "spox": "https://github.com/Quantco/spox",
     "sphinx-gallery": "https://github.com/sphinx-gallery/sphinx-gallery",
+    "tensorflow": "https://www.tensorflow.org/",
+    "tensorflow-onnx": "https://github.com/onnx/tensorflow-onnx",
     "torch": "https://pytorch.org/docs/stable/torch.html",
+    "torch.onnx": "https://pytorch.org/docs/stable/onnx.html",
     #
     "C_OrtValue": (
         "http://www.xavierdupre.fr/app/onnxcustom/helpsphinx/"

_doc/index.rst

@@ -1,5 +1,5 @@
 
-onnx-array-api: (Numpy) Array API for ONNX
+onnx-array-api: APIs to create ONNX Graphs
 ==========================================
 
 .. image:: https://dev.azure.com/xavierdupre3/onnx-array-api/_apis/build/status/sdpython.onnx-array-api
@@ -26,10 +26,8 @@ onnx-array-api: (Numpy) Array API for ONNX
 .. image:: https://codecov.io/gh/sdpython/onnx-array-api/branch/main/graph/badge.svg?token=Wb9ZGDta8J 
     :target: https://codecov.io/gh/sdpython/onnx-array-api
 
-**onnx-array-api** implements a numpy API for ONNX.
-It gives the user the ability to convert functions written
-following the numpy API to convert that function into ONNX as
-well as to execute it.
+**onnx-array-api** implements APIs to create custom ONNX graphs.
+The objective is to speed up the implementation of converter libraries.
 
 .. toctree::
     :maxdepth: 1
@@ -47,6 +45,8 @@ well as to execute it.
     CHANGELOGS
     license
 
+**Numpy API**
+
 Sources available on
 `github/onnx-array-api <https://github.com/sdpython/onnx-array-api>`_.
 
@@ -57,7 +57,7 @@ Sources available on
 
     import numpy as np  # A
     from onnx_array_api.npx import absolute, jit_onnx
-    from onnx_array_api.plotting.dot_plot import to_dot
+    from onnx_array_api.plotting.text_plot import onnx_simple_text_plot
 
     def l1_loss(x, y):
         return absolute(x - y).sum()
@@ -78,6 +78,8 @@ Sources available on
     res = jitted_myloss(x, y)
     print(res)
 
+    print(onnx_simple_text_plot(jitted_myloss.get_onnx()))
+
 .. gdot::
     :script: DOT-SECTION
     :process:
@@ -106,3 +108,30 @@ Sources available on
     y = np.array([[0.11, 0.22], [0.33, 0.44]], dtype=np.float32)
     res = jitted_myloss(x, y)
     print(to_dot(jitted_myloss.get_onnx()))
+
+**Light API**
+
+.. runpython::
+    :showcode:
+
+    import numpy as np
+    from onnx_array_api.light_api import start
+    from onnx_array_api.plotting.text_plot import onnx_simple_text_plot
+
+    model = (
+        start()
+        .vin("X")
+        .vin("Y")
+        .bring("X", "Y")
+        .Sub()
+        .rename("dxy")
+        .cst(np.array([2], dtype=np.int64), "two")
+        .bring("dxy", "two")
+        .Pow()
+        .ReduceSum()
+        .rename("Z")
+        .vout()
+        .to_onnx()
+    )
+
+    print(onnx_simple_text_plot(model))

_doc/tech/aapi.rst

@@ -1,6 +1,7 @@
+.. _l-array-api-painpoint:
 
-Difficulty to implement an an Array API for ONNX
-================================================
+Difficulty to implement an Array API for ONNX
+=============================================
 
 Implementing the full array API is not always easy with :epkg:`onnx`.
 Python is not strongly typed and many different types can be used

_doc/tutorial/index.rst

@@ -6,5 +6,7 @@ Tutorial
 .. toctree::
     :maxdepth: 1
 
-    overview
+    onnx_api
+    light_api
+    numpy_api
     benchmarks

_doc/tutorial/light_api.rst

@@ -0,0 +1,78 @@
+.. _l-light-api:
+
+==========================================
+Light API for ONNX: everything in one line
+==========================================
+
+It is inspired from the :epkg:`reverse Polish notation`.
+Following example implements the euclidean distance.
+This API tries to keep it simple and intuitive to short functions.
+
+.. runpython::
+    :showcode:
+
+    import numpy as np
+    from onnx_array_api.light_api import start
+    from onnx_array_api.plotting.text_plot import onnx_simple_text_plot
+
+    model = (
+        start()
+        .vin("X")
+        .vin("Y")
+        .bring("X", "Y")
+        .Sub()
+        .rename("dxy")
+        .cst(np.array([2], dtype=np.int64), "two")
+        .bring("dxy", "two")
+        .Pow()
+        .ReduceSum()
+        .rename("Z")
+        .vout()
+        .to_onnx()
+    )
+
+    print(onnx_simple_text_plot(model))
+
+There are two kinds of methods, the graph methods, playing with the graph structure,
+and the methods for operators starting with an upper letter.
+
+Graph methods
+=============
+
+Any graph must start with function :func:`start <onnx_array_api.light_api.start>`.
+It is usually following by `vin` to add an input.
+
+* bring (:meth:`Var.bring <onnx_array_api.light_api.Var.bring>`,
+  :meth:`Vars.bring <onnx_array_api.light_api.Vars.bring>`):
+  assembles multiple results into a set before calling an operator taking mulitple inputs,
+* cst (:meth:`Var.cst <onnx_array_api.light_api.Var.cst>`,
+  :meth:`Vars.cst <onnx_array_api.light_api.Vars.cst>`):
+  adds a constant tensor to the graph,
+* rename  (:meth:`Var.rename <onnx_array_api.light_api.Var.rename>`,
+  :meth:`Vars.rename <onnx_array_api.light_api.Vars.rename>`):
+  renames or give a name to a variable in order to call it later.
+* vin (:meth:`Var.vin <onnx_array_api.light_api.Var.vin>`,
+  :meth:`Vars.vin <onnx_array_api.light_api.Vars.vin>`):
+  adds an input to the graph,
+* vout (:meth:`Var.vout <onnx_array_api.light_api.Var.vout>`,
+  :meth:`Vars.vout <onnx_array_api.light_api.Vars.vout>`):
+  declares an existing result as an output.
+
+These methods are implemented in class :class:`onnx_array_api.light_api.var.BaseVar`
+
+Operator methods
+================
+
+They are described in :epkg:`ONNX Operators` and redefined in a stable API
+so that the definition should not change depending on this opset.
+:class:`onnx_array_api.light_api.Var` defines all operators taking only one input.
+:class:`onnx_array_api.light_api.Vars` defines all other operators.
+
+Numpy methods
+=============
+
+Numpy users expect methods such as `reshape`, property `shape` or
+operator `+` to be available as well and that the case. They are
+defined in class :class:`Var <onnx_array_api.light_api.Var>` or
+:class:`Vars <onnx_array_api.light_api.Vars>` depending on the number of
+inputs they require. Their name starts with a lower letter.

_doc/tutorial/overview.rst → _doc/tutorial/numpy_api.rst

@@ -1,3 +1,5 @@
+.. _l-numpy-api-onnx:
+
 ==================
 Numpy API for ONNX
 ==================
@@ -19,6 +21,8 @@ loss functions for example without knowing too much about ONNX.
     The first version (onnx==1.15) does not support control flow yet (test and loops).
     There is no easy syntax for that yet and the main challenge is to deal with local context.
 
+You read :ref:`l-array-api-painpoint` as well.
+
 Overview
 ========