updated docs

v923z · v923z · commit 208fa196ab95 · 2021-01-15T16:03:40.000+01:00
diff --git a/docs/manual/source/conf.py b/docs/manual/source/conf.py
@@ -27,7 +27,7 @@
 author = 'Zoltán Vörös'
 
 # The full version, including alpha/beta/rc tags
-release = '2.1.1'
+release = '2.1.2'
 
 
 # -- General configuration ---------------------------------------------------
diff --git a/docs/manual/source/index.rst b/docs/manual/source/index.rst
@@ -14,7 +14,7 @@ Welcome to the ulab book!
    ulab-intro
 
 .. toctree::
-   :maxdepth: 3
+   :maxdepth: 2
    :caption: User's guide:
 
    ulab-ndarray
diff --git a/docs/manual/source/numpy-fft.rst b/docs/manual/source/numpy-fft.rst
@@ -1,4 +1,4 @@
-None
+
 Fourier transforms
 ==================
 
diff --git a/docs/manual/source/numpy-functions.rst b/docs/manual/source/numpy-functions.rst
@@ -1,4 +1,4 @@
-None
+
 Numpy functions
 ===============
 
@@ -20,7 +20,7 @@ from ``numpy``.
 13. `numpy.median <#median>`__
 14. `numpy.min <#min>`__
 15. `numpy.minimum <#minimum>`__
-16. `numpy.not_equal <#not_equal>`__
+16. `numpy.not_equal <#equal>`__
 17. `numpy.polyfit <#polyfit>`__
 18. `numpy.polyval <#polyval>`__
 19. `numpy.roll <#roll>`__
@@ -570,22 +570,13 @@ https://docs.scipy.org/doc/numpy/reference/generated/numpy.min.html
 
 See `numpy.max <#max>`__.
 
-.. code::
-
-    # code to be run in CPython
-    
-
 minimum
 -------
 
 ``numpy``:
 https://docs.scipy.org/doc/numpy/reference/generated/numpy.minimum.html
 
-Returns the minimum of two arrays, or two scalars, or an array, and a
-scalar. If the arrays are of different ``dtype``, the output is upcast
-as in `Binary operators <#Binary-operators>`__. If both inputs are
-scalars, a scalar is returned. Only positional arguments are
-implemented.
+See `numpy.maximum <#maximum>`__
 
 maximum
 -------
@@ -1045,8 +1036,3 @@ points corresponding to ``y``.
     
     
 
-
-.. code::
-
-    # code to be run in CPython
-    
diff --git a/docs/manual/source/numpy-linalg.rst b/docs/manual/source/numpy-linalg.rst
@@ -1,4 +1,4 @@
-None
+
 Linalg
 ======
 
diff --git a/docs/manual/source/numpy-universal.rst b/docs/manual/source/numpy-universal.rst
@@ -1,4 +1,4 @@
-None
+
 Universal functions
 ===================
 
diff --git a/docs/manual/source/scipy-optimize.rst b/docs/manual/source/scipy-optimize.rst
@@ -1,4 +1,4 @@
-None
+
 Optimize
 ========
 
diff --git a/docs/manual/source/scipy-signal.rst b/docs/manual/source/scipy-signal.rst
@@ -1,4 +1,4 @@
-None
+
 Signal
 ======
 
diff --git a/docs/manual/source/scipy-special.rst b/docs/manual/source/scipy-special.rst
@@ -1,4 +1,4 @@
-None
+
 Special functions
 =================
 
diff --git a/docs/manual/source/ulab-intro.rst b/docs/manual/source/ulab-intro.rst
@@ -1,4 +1,4 @@
-None
+
 Introduction
 ============
 
@@ -101,7 +101,7 @@ approximately 120 kB of extra compiled code to the ``micropython``
 can easily shave tens of kB off the firmware. In fact, if only a small
 sub-set of functions are needed, you can get away with less than 10 kB
 of flash space. See the section on `customising
-ulab <#Custom_builds>`__.
+ulab <#Customising-the-firmware>`__.
 
 Resources and legal matters
 ---------------------------
@@ -145,13 +145,13 @@ implementation details only, which all have been sorted out with the
 generous and enthusiastic support of Jeff Epler from `Adafruit
 Industries <http://www.adafruit.com>`__.
 
-There are, however, a couple of instances, where the usage in the two
-environments is different at the python level. These are how the class
-properties can be accessed. We will point out the differences and
-possible workarounds at the relevant places in this document.
+There are, however, a couple of instances, where the two environments
+differ at the python level in how the class properties can be accessed.
+We will point out the differences and possible workarounds at the
+relevant places in this document.
 
-Customising ``ulab``
-====================
+Customising the firmware
+========================
 
 As mentioned above, ``ulab`` has considerably grown since its
 conception, which also means that it might no longer fit on the
@@ -587,8 +587,3 @@ the
    #define NDARRAY_HAS_BINARY_OP_POWER         (0)
 
 definition.
-
-.. code::
-
-    # code to be run in CPython
-    
diff --git a/docs/manual/source/ulab-ndarray.rst b/docs/manual/source/ulab-ndarray.rst
@@ -1,6 +1,6 @@
-None
-ndarray, the basic container
-============================
+
+ndarray, the base class
+=======================
 
 The ``ndarray`` is the underlying container of numerical data. It can be
 thought of as micropython’s own ``array`` object, but has a great number
@@ -250,7 +250,17 @@ type, or performance is important.
 Array initialisation functions
 ------------------------------
 
-There are seven functions that can be used for initialising an array.
+There are nine functions that can be used for initialising an array.
+
+1. `numpy.arange <#arange>`__
+2. `numpy.concatenate <#concatenate>`__
+3. `numpy.eye <#eye>`__
+4. `numpy.frombuffer <#frombuffer>`__
+5. `numpy.full <#full>`__
+6. `numpy.linspace <#linspace>`__
+7. `numpy.logspace <#logspace>`__
+8. `numpy.ones <#ones>`__
+9. `numpy.zeros <#zeros>`__
 
 arange
 ~~~~~~
@@ -442,6 +452,52 @@ Specifying the dimensions of the matrix
     
 
 
+frombuffer
+~~~~~~~~~~
+
+``numpy``:
+https://numpy.org/doc/stable/reference/generated/numpy.frombuffer.html
+
+The function interprets a contiguous buffer as a one-dimensional array,
+and thus can be used for piping buffered data directly into an array.
+This method of analysing, e.g., ADC data is much more efficient than
+passing the ADC buffer into the ``array`` constructor, because
+``frombuffer`` simply creates the ``ndarray`` header and blindly copies
+the memory segment, without inspecting the underlying data.
+
+The function takes a single positional argument, the buffer, and three
+keyword arguments. These are the ``dtype`` with a default value of
+``float``, the ``offset``, with a default of 0, and the ``count``, with
+a default of -1, meaning that all data are taken in.
+
+.. code::
+        
+    # code to be run in micropython
+    
+    from ulab import numpy as np
+    
+    buffer = b'\x01\x02\x03\x04\x05\x06\x07\x08'
+    print('buffer: ', buffer)
+    
+    a = np.frombuffer(buffer, dtype=np.uint8)
+    print('a, all data read: ', a)
+    
+    b = np.frombuffer(buffer, dtype=np.uint8, offset=2)
+    print('b, all data with an offset: ', b)
+    
+    c = np.frombuffer(buffer, dtype=np.uint8, offset=2, count=3)
+    print('c, only 3 items with an offset: ', c)
+
+.. parsed-literal::
+
+    buffer:  b'\x01\x02\x03\x04\x05\x06\x07\x08'
+    a, all data read:  array([1, 2, 3, 4, 5, 6, 7, 8], dtype=uint8)
+    b, all data with an offset:  array([3, 4, 5, 6, 7, 8], dtype=uint8)
+    c, only 3 items with an offset:  array([3, 4, 5], dtype=uint8)
+    
+    
+
+
 full
 ~~~~
 
@@ -2285,8 +2341,3 @@ view is really nothing but a short header with a data array that already
 exists, and is filled up. Hence, creating the view requires only the
 creation of its header. This operation is fast, and uses virtually no
 RAM.
-
-.. code::
-
-    # code to be run in CPython
-    
diff --git a/docs/manual/source/ulab-programming.rst b/docs/manual/source/ulab-programming.rst
@@ -1,4 +1,4 @@
-None
+
 Programming ulab
 ================
 
@@ -909,8 +909,3 @@ function are
    MP_DEFINE_CONST_FUN_OBJ_N()
 3. Binding this function object to the namespace in the
    ``ulab_user_globals_table[]``
-
-.. code::
-
-    # code to be run in CPython
-    
diff --git a/docs/numpy-functions.ipynb b/docs/numpy-functions.ipynb
@@ -247,7 +247,7 @@
     "1. [numpy.median](#median)\n",
     "1. [numpy.min](#min)\n",
     "1. [numpy.minimum](#minimum)\n",
-    "1. [numpy.not_equal](#not_equal)\n",
+    "1. [numpy.not_equal](#equal)\n",
     "1. [numpy.polyfit](#polyfit)\n",
     "1. [numpy.polyval](#polyval)\n",
     "1. [numpy.roll](#roll)\n",
@@ -916,13 +916,6 @@
     "See [numpy.max](#max)."
    ]
   },
-  {
-   "cell_type": "code",
-   "execution_count": null,
-   "metadata": {},
-   "outputs": [],
-   "source": []
-  },
   {
    "cell_type": "markdown",
    "metadata": {},
@@ -931,8 +924,13 @@
     "\n",
     "`numpy`: https://docs.scipy.org/doc/numpy/reference/generated/numpy.minimum.html\n",
     "\n",
-    "Returns the minimum of two arrays, or two scalars, or an array, and a scalar. If the arrays are of different `dtype`, the output is upcast as in [Binary operators](#Binary-operators). If both inputs are scalars, a scalar is returned. Only positional arguments are implemented.\n",
-    "\n",
+    "See [numpy.maximum](#maximum)"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
     "## maximum\n",
     "\n",
     "`numpy`: https://docs.scipy.org/doc/numpy/reference/generated/numpy.maximum.html\n",
@@ -1520,13 +1518,6 @@
     "print('integral of y: ', np.trapz(y))\n",
     "print('integral of y at x: ', np.trapz(y, x=x))"
    ]
-  },
-  {
-   "cell_type": "code",
-   "execution_count": null,
-   "metadata": {},
-   "outputs": [],
-   "source": []
   }
  ],
  "metadata": {
diff --git a/docs/ulab-convert.ipynb b/docs/ulab-convert.ipynb
@@ -14,11 +14,11 @@
   },
   {
    "cell_type": "code",
-   "execution_count": 7,
+   "execution_count": 1,
    "metadata": {
     "ExecuteTime": {
-     "end_time": "2021-01-14T17:57:42.304478Z",
-     "start_time": "2021-01-14T17:57:42.205232Z"
+     "end_time": "2021-01-15T13:53:42.464150Z",
+     "start_time": "2021-01-15T13:53:42.449894Z"
     }
    },
    "outputs": [
@@ -61,7 +61,7 @@
     "author = 'Zoltán Vörös'\n",
     "\n",
     "# The full version, including alpha/beta/rc tags\n",
-    "release = '2.1.1'\n",
+    "release = '2.1.2'\n",
     "\n",
     "\n",
     "# -- General configuration ---------------------------------------------------\n",
@@ -148,11 +148,11 @@
   },
   {
    "cell_type": "code",
-   "execution_count": 2,
+   "execution_count": 35,
    "metadata": {
     "ExecuteTime": {
-     "end_time": "2021-01-14T16:17:06.823520Z",
-     "start_time": "2021-01-14T16:17:06.759683Z"
+     "end_time": "2021-01-15T14:18:49.025168Z",
+     "start_time": "2021-01-15T14:18:49.015858Z"
     }
    },
    "outputs": [
@@ -182,7 +182,7 @@
     "   ulab-intro\n",
     "\n",
     ".. toctree::\n",
-    "   :maxdepth: 3\n",
+    "   :maxdepth: 2\n",
     "   :caption: User's guide:\n",
     "\n",
     "   ulab-ndarray\n",
@@ -212,11 +212,11 @@
   },
   {
    "cell_type": "code",
-   "execution_count": 4,
+   "execution_count": 31,
    "metadata": {
     "ExecuteTime": {
-     "end_time": "2021-01-14T16:19:01.938959Z",
-     "start_time": "2021-01-14T16:18:59.040730Z"
+     "end_time": "2021-01-15T14:09:47.022621Z",
+     "start_time": "2021-01-15T14:09:46.985214Z"
     }
    },
    "outputs": [],
@@ -234,6 +234,7 @@
     "def convert_notebook(fn):\n",
     "    source = nb.read(fn+'.ipynb', nb.NO_CONVERT)\n",
     "    notebook = nb4.new_notebook()\n",
+    "    notebook.cells = []\n",
     "    append_cell = False\n",
     "    for cell in source['cells']:\n",
     "        if append_cell:\n",
@@ -245,16 +246,17 @@
     "                    \n",
     "    (rst, resources) = rstexporter.from_notebook_node(notebook)\n",
     "    with open('./manual/source/' + fn + '.rst', 'w') as fout:\n",
+    "        # it's a bit odd, but even an emtpy notebook is converted into a \"None\" string\n",
+    "        rst = rst.lstrip('None')\n",
     "        fout.write(rst)"
    ]
   },
   {
    "cell_type": "code",
-   "execution_count": 5,
+   "execution_count": null,
    "metadata": {
     "ExecuteTime": {
-     "end_time": "2021-01-14T16:19:15.242085Z",
-     "start_time": "2021-01-14T16:19:01.955650Z"
+     "start_time": "2021-01-15T14:38:15.993Z"
     }
    },
    "outputs": [],
diff --git a/docs/ulab-intro.ipynb b/docs/ulab-intro.ipynb
diff --git a/docs/ulab-ndarray.ipynb b/docs/ulab-ndarray.ipynb
diff --git a/docs/ulab-programming.ipynb b/docs/ulab-programming.ipynb

Original file line number	Diff line number	Diff line change
`@@ -1,4 +1,4 @@`
`1`		`-None`
	`1`	`+`
`2`	`2`	`Fourier transforms`
`3`	`3`	`==================`
`4`	`4`
Original file line number	Diff line number	Diff line change
`@@ -1,4 +1,4 @@`
`1`		`-None`
	`1`	`+`
`2`	`2`	`Linalg`
`3`	`3`	`======`
`4`	`4`
Original file line number	Diff line number	Diff line change
`@@ -1,4 +1,4 @@`
`1`		`-None`
	`1`	`+`
`2`	`2`	`Universal functions`
`3`	`3`	`===================`
`4`	`4`
Original file line number	Diff line number	Diff line change
`@@ -1,4 +1,4 @@`
`1`		`-None`
	`1`	`+`
`2`	`2`	`Optimize`
`3`	`3`	`========`
`4`	`4`
Original file line number	Diff line number	Diff line change
`@@ -1,4 +1,4 @@`
`1`		`-None`
	`1`	`+`
`2`	`2`	`Signal`
`3`	`3`	`======`
`4`	`4`
Original file line number	Diff line number	Diff line change
`@@ -1,4 +1,4 @@`
`1`		`-None`
	`1`	`+`
`2`	`2`	`Special functions`
`3`	`3`	`=================`
`4`	`4`