Update docs with tutorials and how-to sections

doc/api.rst

@@ -1,3 +1,4 @@
+.. _API:
 .. currentmodule:: rbc
 
 =============

doc/conf.py

@@ -53,8 +53,12 @@
     'sphinx.ext.napoleon',
     'sphinx.ext.autosectionlabel',
     'numbadoc',
+    'sphinx_design',
+    'myst_parser',
 ]
 
+myst_enable_extensions = ["colon_fence"]
+
 # autosummary configuration
 autosummary_generate = True
 autodoc_typehints = "description"

doc/developer.rst

@@ -41,7 +41,7 @@ Then, to create an environment with a few of the most common dependencies:
 
 To activate the environment for the current shell session:
 
-.. code-block:: console
+.. code-block:: bash
 
     $ conda activate rbc
 
@@ -52,7 +52,7 @@ To activate the environment for the current shell session:
 Once the environment is activated, you have a dedicated Python with the
 required dependencies:
 
-.. code-block:: python
+.. code-block:: bash
 
     $ python
     >>> import llvmlite

doc/howto.md

@@ -0,0 +1,51 @@
+
+# RBC how-tos
+
+These documents are intended as short recipes for common tasks using RBC. It is
+based on [NumPy how-tos](https://numpy.org/devdocs/user/howtos_index.html) and
+[diataxis how to guide](https://diataxis.fr/how-to-guides/).
+
+How-tos are supposed to be short documents describing a specific feature or
+property of the RBC project. For full content, check the tutorials page.
+
+```{toctree}
+---
+maxdepth: 1
+caption: Basics
+---
+
+howtos/connect
+howtos/udf
+howtos/udtf
+howtos/raise_exception
+howtos/template
+```
+
+-----
+
+
+```{toctree}
+---
+maxdepth: 1
+caption: Datatypes
+---
+
+howtos/array
+howtos/column
+howtos/text
+howtos/geo
+howtos/manager
+howtos/string_dict_proxy
+```
+
+-----
+
+```{toctree}
+---
+maxdepth: 1
+caption: Advanced
+---
+
+howtos/devices
+howtos/external_functions
+```

doc/howtos/array.md

@@ -0,0 +1,82 @@
+# Array type
+
+Arrays provide a convenient way to represent a sequence of values of the same
+type.
+
+## Basics
+
+### Building an array
+
+```{literalinclude} ../../rbc/tests/heavydb/test_howtos.py
+:language: python
+:caption: from ``test_udf_array`` of ``rbc/tests/heavydb/test_howtos.py``
+:start-after: magictoken.udf.array.new.begin
+:end-before: magictoken.udf.array.new.end
+:dedent: 4
+:linenos:
+```
+
+:::{dropdown} Example SQL Query
+
+```{literalinclude} ../../rbc/tests/heavydb/test_howtos.py
+:language: python
+:caption: from ``test_geopoint`` of ``rbc/tests/heavydb/test_howtos.py``
+:start-after: magictoken.udf.array.new.sql.begin
+:end-before: magictoken.udf.array.new.sql.end
+:dedent: 4
+:linenos:
+```
+
+:::
+
+
+### Computing the length of an array
+
+```{literalinclude} ../../rbc/tests/heavydb/test_howtos.py
+:language: python
+:caption: from ``test_udf_array`` of ``rbc/tests/heavydb/test_howtos.py``
+:start-after: magictoken.udf.array.length.begin
+:end-before: magictoken.udf.array.length.end
+:dedent: 4
+:linenos:
+```
+
+:::{dropdown} Example SQL Query
+
+```{literalinclude} ../../rbc/tests/heavydb/test_howtos.py
+:language: python
+:caption: from ``test_geopoint`` of ``rbc/tests/heavydb/test_howtos.py``
+:start-after: magictoken.udf.array.length.sql.begin
+:end-before: magictoken.udf.array.length.sql.end
+:dedent: 4
+:linenos:
+```
+
+:::
+
+### Using the [array_api](https://data-apis.org/array-api/2022.12/)
+
+RBC partially implements the array api standard. For a list of supported
+functions, check the [API](API) page.
+
+```{literalinclude} ../../rbc/tests/heavydb/test_howtos.py
+:language: python
+:caption: from ``test_udf_array`` of ``rbc/tests/heavydb/test_howtos.py``
+:start-after: magictoken.udf.array.array_api.begin
+:end-before: magictoken.udf.array.array_api.end
+:dedent: 4
+:linenos:
+```
+
+:::{dropdown} Example SQL Query
+
+```{literalinclude} ../../rbc/tests/heavydb/test_howtos.py
+:language: python
+:caption: from ``test_geopoint`` of ``rbc/tests/heavydb/test_howtos.py``
+:start-after: magictoken.udf.array.array_api.sql.begin
+:end-before: magictoken.udf.array.array_api.sql.end
+:dedent: 4
+:linenos:
+```
+
+:::

doc/howtos/column.md

@@ -0,0 +1,28 @@
+# Column Type
+
+The Column type provides the structure and organization for storing and
+retrieving columnar data within HeavyDB.
+
+## Basic usage
+
+```{literalinclude} ../../rbc/tests/heavydb/test_howtos.py
+:language: python
+:caption: from ``test_column_power`` of ``rbc/tests/heavydb/test_howtos.py``
+:start-after: magictoken.udtf.column.basic.begin
+:end-before: magictoken.udtf.column.basic.end
+:dedent: 4
+:linenos:
+```
+
+:::{dropdown} Example SQL Query
+
+```{literalinclude} ../../rbc/tests/heavydb/test_howtos.py
+:language: python
+:caption: from ``test_column`` of ``rbc/tests/heavydb/test_howtos.py``
+:start-after: magictoken.udtf.column.basic.sql.begin
+:end-before: magictoken.udtf.column.basic.sql.end
+:dedent: 4
+:linenos:
+```
+
+:::

doc/howtos/connect.md

@@ -0,0 +1,12 @@
+
+(heavydb-connect)=
+# Connect to the HeavyDB server
+
+```{literalinclude} ../../rbc/tests/heavydb/test_howtos.py
+:language: python
+:caption: from ``test_connect`` of ``rbc/tests/heavydb/test_howtos.py``
+:start-after: magictoken.connect.begin
+:end-before: magictoken.connect.end
+:dedent: 4
+:linenos:
+```

doc/howtos/devices.md

@@ -0,0 +1,25 @@
+# Restricting a function to run only in a specific device (CPU/GPU)
+
+Assuming you already have a [connection](heavydb-connect) to the HeavyDB server:
+
+```{literalinclude} ../../rbc/tests/heavydb/test_howtos.py
+:language: python
+:caption: from ``test_devices`` of ``rbc/tests/heavydb/test_howtos.py``
+:start-after: magictoken.devices.begin
+:end-before: magictoken.devices.end
+:dedent: 4
+:linenos:
+```
+
+By default, both devices are used if available. Otherwise, only the CPU is used.
+
+:::{dropdown} Example SQL Query
+```{literalinclude} ../../rbc/tests/heavydb/test_howtos.py
+:language: python
+:caption: from ``test_devices`` of ``rbc/tests/heavydb/test_howtos.py``
+:start-after: magictoken.devices.sql.begin
+:end-before: magictoken.devices.sql.end
+:dedent: 4
+:linenos:
+```
+:::

doc/howtos/external_functions.md

@@ -0,0 +1,52 @@
+
+# Defining and using external functions
+
+## cmath `abs`
+
+The `external` keyword provides a way of calling C functions defined in other
+libraries within Python code.
+
+```{literalinclude} ../../rbc/tests/heavydb/test_howtos.py
+:language: python
+:caption: from ``test_external_functions`` of ``rbc/tests/heavydb/test_howtos.py``
+:start-after: magictoken.external_functions.abs.begin
+:end-before: magictoken.external_functions.abs.end
+:dedent: 4
+:linenos:
+```
+
+:::{dropdown} Example SQL Query
+```{literalinclude} ../../rbc/tests/heavydb/test_howtos.py
+:language: python
+:caption: from ``test_external_functions`` of ``rbc/tests/heavydb/test_howtos.py``
+:start-after: magictoken.external_functions.abs.sql.begin
+:end-before: magictoken.external_functions.abs.sql.end
+:dedent: 4
+:linenos:
+```
+:::
+
+RBC already exposes a small set of C functions from the C stdlib. Check the API
+reference page for more details.
+
+## Using `printf`
+
+```{literalinclude} ../../rbc/tests/heavydb/test_howtos.py
+:language: python
+:caption: from ``test_external_functions`` of ``rbc/tests/heavydb/test_howtos.py``
+:start-after: magictoken.external_functions.printf.begin
+:end-before: magictoken.external_functions.printf.end
+:dedent: 4
+:linenos:
+```
+
+:::{dropdown} Example SQL Query
+```{literalinclude} ../../rbc/tests/heavydb/test_howtos.py
+:language: python
+:caption: from ``test_external_functions`` of ``rbc/tests/heavydb/test_howtos.py``
+:start-after: magictoken.external_functions.printf.sql.begin
+:end-before: magictoken.external_functions.printf.sql.end
+:dedent: 4
+:linenos:
+```
+:::

doc/howtos/geo.md

@@ -0,0 +1,58 @@
+# Geometry Types
+
+HeavyDB offers an extensive range of geometry types, encompassing
+`(Multi)Point`, `(Multi)LineString`, and `(Multi)Polygon`.
+
+## Basics
+
+### `GeoPoint`
+
+```{literalinclude} ../../rbc/tests/heavydb/test_howtos.py
+:language: python
+:caption: from ``test_geopoint`` of ``rbc/tests/heavydb/test_howtos.py``
+:start-after: magictoken.udtf.geopoint.basic.begin
+:end-before: magictoken.udtf.geopoint.basic.end
+:dedent: 4
+:linenos:
+```
+
+:::{dropdown} Example SQL Query
+
+```{literalinclude} ../../rbc/tests/heavydb/test_howtos.py
+:language: python
+:caption: from ``test_geopoint`` of ``rbc/tests/heavydb/test_howtos.py``
+:start-after: magictoken.udtf.geopoint.basic.sql.begin
+:end-before: magictoken.udtf.geopoint.basic.sql.end
+:dedent: 4
+:linenos:
+```
+
+:::
+
+
+### `GeoMultiPoint`
+
+`MultiPoint` works a bit different than `Point`. They are created by calling
+the `.from_coords` method.
+
+```{literalinclude} ../../rbc/tests/heavydb/test_howtos.py
+:language: python
+:caption: from ``test_geomultipoint`` of ``rbc/tests/heavydb/test_howtos.py``
+:start-after: magictoken.udtf.mp.basic.begin
+:end-before: magictoken.udtf.mp.basic.end
+:dedent: 4
+:linenos:
+```
+
+:::{dropdown} Example SQL Query
+
+```{literalinclude} ../../rbc/tests/heavydb/test_howtos.py
+:language: python
+:caption: from ``test_geopoint`` of ``rbc/tests/heavydb/test_howtos.py``
+:start-after: magictoken.udtf.mp.basic.sql.begin
+:end-before: magictoken.udtf.mp.basic.sql.end
+:dedent: 4
+:linenos:
+```
+
+:::