Update docs with tutorials and howto sections

doc/conf.py

@@ -53,6 +53,7 @@
     'sphinx.ext.napoleon',
     'sphinx.ext.autosectionlabel',
     'numbadoc',
+    'myst_parser',
 ]
 
 # autosummary configuration
@@ -79,7 +80,7 @@
 # The theme to use for HTML and HTML Help pages.  See the documentation for
 # a list of builtin themes.
 #
-html_theme = 'pydata_sphinx_theme'
+html_theme = 'furo'
 
 # The Xnd logo
 html_logo = "images/xndlogo.png"

doc/howto.md

@@ -0,0 +1,21 @@
+
+## 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
+---
+
+howtos/connect
+howtos/devices
+howtos/external_functions
+howtos/raise_exception
+howtos/template
+```

doc/howtos/connect.md

@@ -0,0 +1,9 @@
+
+(heavydb-connect)=
+## Connect to the HeavyDB server
+
+```python
+from rbc.heavydb import RemoteHeavyDB
+heavydb = RemoteHeavyDB(user='admin', password='HyperInteractive',
+                        host='127.0.0.1', port=6274)
+```

doc/howtos/devices.md

@@ -0,0 +1,12 @@
+
+## Stricting a function to run in a specific device (CPU/GPU)
+
+Assuming you already have a [connection](heavydb-connect) to the HeavyDB server:
+
+```python
+@heavydb('int32(int32, int32)', devices=['CPU', 'GPU'])
+def add(a, b):
+    return a + b
+```
+
+By default, both devices are used if available. Otherwise, only the CPU is used.

doc/howtos/external_functions.md

@@ -0,0 +1,33 @@
+
+## Defining and using external functions
+
+The `external` keyword provide a way of calling C functions defined in other
+libraries within python code.
+
+```python
+from rbc.external import external
+cmath_abs = external('int64 abs(int64)')
+
+@heavydb('int64(int64)')
+def apply_abs(x):
+    return cmath_abs(x)
+
+heavydb.sql_execute('SELECT apply_abs(-3);')
+```
+
+RBC already exposes a small set of C functions from the C stdlib. Check the API
+reference page for more details.
+
+### Using `printf`
+
+```python
+from rbc.externals.stdio import printf
+
+@heavydb('int64(int64)')
+def power_2(x):
+    # This message will show in the heavydb logs
+    printf("input number: %d\n", x)
+    return x * x
+
+heavydb.sql_execute('SELECT power_2(3);')
+```

doc/howtos/raise_exception.md

@@ -0,0 +1,27 @@
+
+## Raising exceptions
+
+Exceptions in HeavyDB are quite different from the ones used in Python. In RBC
+code, you signal to the database an exception happened by calling a specific
+method (`error_message`) in the runner manager.
+
+### In a UDTF
+
+```python
+@heavydb('int32(TableFunctionManager, Column<int>, OutputColumn<int>)')
+def udtf_copy(mgr, inp, out):
+    size = len(inp)
+    if size > 5:
+        # error message must be known at compile-time
+        return mgr.error_message('Can only copy up to 5 rows')
+
+    mgr.set_output_row_size(size)
+    for i in range(size):
+        out[i] = inp[i]
+    return size
+```
+
+### In a UDF:
+
+It is currently not possible to raise an exception in a UDF. The server must
+implement support for it first before RBC can support it.

doc/howtos/template.md

@@ -0,0 +1,17 @@
+
+## Using templates
+
+Templates are generic types used in the decorator `@heavydb`. Templating allows
+the target function to accept different data types for its arguments.
+
+Assuming you already have a [connection](heavydb-connect) to the HeavyDB server:
+
+```python
+@heavydb('Z(T, Z)', T=['int32', 'float'], Z=['int64', 'double'])
+def add(a, b):
+    return a + b
+```
+
+In the case above, the template arguments `T` and `Z`, are specified within the
+decorator, indicating the valid data types that can be used for the `add`
+function.

doc/index.rst

@@ -15,12 +15,25 @@ A Python package implementing a remote backend compiler using numba
 and llvmlite tools.
 
 .. toctree::
+   :caption: Getting started
    :maxdepth: 1
-   :caption: Contents:
 
    design
+   installation
+
+.. toctree::
+   :caption: Fundamentals and usage
+   :maxdepth: 1
+
+   howto
+   tutorials
+
+.. toctree::
+   :maxdepth: 1
+   :caption: Reference Manual:
+
    api
-   releases
+   envvars
    developer
    nrt
-   envvars
+   releases

doc/installation.md

@@ -0,0 +1,24 @@
+
+## Installation
+
+RBC is available on both conda-forge and PyPI.
+
+### conda/mamba
+
+You can use either [conda](https://docs.conda.io/projects/conda/en/latest/user-guide/install/index.html)
+or [mamba](https://github.com/mamba-org/mamba) to install RBC. We suggest using
+mamba as it uses a faster solver.
+
+```bash
+conda create --name rbc_env
+conda activate rbc_env
+conda install -c conda-forge rbc
+```
+
+### Pip
+
+On PyPI, the RBC library is called `rbc-project`.
+
+```bash
+pip install rbc-project
+```

doc/tutorials.md

@@ -0,0 +1,11 @@
+
+## RBC tutorials
+
+Different from how to guides, tutorials are longer and cover a broader set of
+features available in the RBC project. These tutorials are usually jupyter
+notebooks available in the `notebooks` repo and rendered here.
+
+* [RBC intro](https://github.com/xnd-project/rbc/blob/main/notebooks/rbc-intro.ipynb)
+* [Using RBC with Ibis](https://github.com/xnd-project/rbc/blob/main/notebooks/rbc-heavydb-ibis.ipynb)
+* [Defining and using external functions](https://github.com/xnd-project/rbc/blob/main/notebooks/rbc-heavydb-external-fns.ipynb)
+* [Case study - Black Scholes model](https://github.com/xnd-project/rbc/blob/main/notebooks/rbc-heavydb-black-scholes.ipynb)

test_requirements.txt

@@ -4,7 +4,8 @@ tblib
 thriftpy2
 netifaces
 clang==11.1.0
-pydata-sphinx-theme>=0.9.0
+furo
+myst-parser
 packaging
 setuptools
 urllib3<2