Skip to content

Commit dcfc843

Browse files
guilhermeleobasguilhermeleobas
authored
Update docs with tutorials and how-to sections (#569)
* Update docs with tutorials and howto sections * test functions on how-to guide on CI * Add examples for arrays, text, udf and udtf * Add how-to for string, table/row function manager and text type * render tutorials with nbviewer * Update tutorial name * fix notebook link * undo changes to api.rst * Add basic usage of GeoPoint * add sphinx-design extension * Add MultiPoint how-to section * update column.md to show dropdown menu with sample SQL query * Add SQL snippet * Add example SQL query for all how-to pages * flake8 * Change heading to H1 * Fix tests after rebase * address reviewer comments * flake8
1 parent f62c0f0 commit dcfc843

29 files changed

+1217
-11
lines changed

‎doc/api.rst

+1
Original file line numberDiff line numberDiff line change
@@ -1,3 +1,4 @@
1+
.. _API:
12
.. currentmodule:: rbc
23

34
=============

‎doc/conf.py

+4
Original file line numberDiff line numberDiff line change
@@ -53,8 +53,12 @@
5353
'sphinx.ext.napoleon',
5454
'sphinx.ext.autosectionlabel',
5555
'numbadoc',
56+
'sphinx_design',
57+
'myst_parser',
5658
]
5759

60+
myst_enable_extensions = ["colon_fence"]
61+
5862
# autosummary configuration
5963
autosummary_generate = True
6064
autodoc_typehints = "description"

‎doc/developer.rst

+2-2
Original file line numberDiff line numberDiff line change
@@ -41,7 +41,7 @@ Then, to create an environment with a few of the most common dependencies:
4141

4242
To activate the environment for the current shell session:
4343

44-
.. code-block:: console
44+
.. code-block:: bash
4545
4646
$ conda activate rbc
4747
@@ -52,7 +52,7 @@ To activate the environment for the current shell session:
5252
Once the environment is activated, you have a dedicated Python with the
5353
required dependencies:
5454

55-
.. code-block:: python
55+
.. code-block:: bash
5656
5757
$ python
5858
>>> import llvmlite

‎doc/getting_started.rst

Whitespace-only changes.

‎doc/howto.md

+51
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,51 @@
1+
2+
# RBC how-tos
3+
4+
These documents are intended as short recipes for common tasks using RBC. It is
5+
based on [NumPy how-tos](https://numpy.org/devdocs/user/howtos_index.html) and
6+
[diataxis how to guide](https://diataxis.fr/how-to-guides/).
7+
8+
How-tos are supposed to be short documents describing a specific feature or
9+
property of the RBC project. For full content, check the tutorials page.
10+
11+
```{toctree}
12+
---
13+
maxdepth: 1
14+
caption: Basics
15+
---
16+
17+
howtos/connect
18+
howtos/udf
19+
howtos/udtf
20+
howtos/raise_exception
21+
howtos/template
22+
```
23+
24+
-----
25+
26+
27+
```{toctree}
28+
---
29+
maxdepth: 1
30+
caption: Datatypes
31+
---
32+
33+
howtos/array
34+
howtos/column
35+
howtos/text
36+
howtos/geo
37+
howtos/manager
38+
howtos/string_dict_proxy
39+
```
40+
41+
-----
42+
43+
```{toctree}
44+
---
45+
maxdepth: 1
46+
caption: Advanced
47+
---
48+
49+
howtos/devices
50+
howtos/external_functions
51+
```

‎doc/howtos/array.md

+82
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,82 @@
1+
# Array type
2+
3+
Arrays provide a convenient way to represent a sequence of values of the same
4+
type.
5+
6+
## Basics
7+
8+
### Building an array
9+
10+
```{literalinclude} ../../rbc/tests/heavydb/test_howtos.py
11+
:language: python
12+
:caption: from ``test_udf_array`` of ``rbc/tests/heavydb/test_howtos.py``
13+
:start-after: magictoken.udf.array.new.begin
14+
:end-before: magictoken.udf.array.new.end
15+
:dedent: 4
16+
:linenos:
17+
```
18+
19+
:::{dropdown} Example SQL Query
20+
21+
```{literalinclude} ../../rbc/tests/heavydb/test_howtos.py
22+
:language: python
23+
:caption: from ``test_geopoint`` of ``rbc/tests/heavydb/test_howtos.py``
24+
:start-after: magictoken.udf.array.new.sql.begin
25+
:end-before: magictoken.udf.array.new.sql.end
26+
:dedent: 4
27+
:linenos:
28+
```
29+
30+
:::
31+
32+
33+
### Computing the length of an array
34+
35+
```{literalinclude} ../../rbc/tests/heavydb/test_howtos.py
36+
:language: python
37+
:caption: from ``test_udf_array`` of ``rbc/tests/heavydb/test_howtos.py``
38+
:start-after: magictoken.udf.array.length.begin
39+
:end-before: magictoken.udf.array.length.end
40+
:dedent: 4
41+
:linenos:
42+
```
43+
44+
:::{dropdown} Example SQL Query
45+
46+
```{literalinclude} ../../rbc/tests/heavydb/test_howtos.py
47+
:language: python
48+
:caption: from ``test_geopoint`` of ``rbc/tests/heavydb/test_howtos.py``
49+
:start-after: magictoken.udf.array.length.sql.begin
50+
:end-before: magictoken.udf.array.length.sql.end
51+
:dedent: 4
52+
:linenos:
53+
```
54+
55+
:::
56+
57+
### Using the [array_api](https://data-apis.org/array-api/2022.12/)
58+
59+
RBC partially implements the array api standard. For a list of supported
60+
functions, check the [API](API) page.
61+
62+
```{literalinclude} ../../rbc/tests/heavydb/test_howtos.py
63+
:language: python
64+
:caption: from ``test_udf_array`` of ``rbc/tests/heavydb/test_howtos.py``
65+
:start-after: magictoken.udf.array.array_api.begin
66+
:end-before: magictoken.udf.array.array_api.end
67+
:dedent: 4
68+
:linenos:
69+
```
70+
71+
:::{dropdown} Example SQL Query
72+
73+
```{literalinclude} ../../rbc/tests/heavydb/test_howtos.py
74+
:language: python
75+
:caption: from ``test_geopoint`` of ``rbc/tests/heavydb/test_howtos.py``
76+
:start-after: magictoken.udf.array.array_api.sql.begin
77+
:end-before: magictoken.udf.array.array_api.sql.end
78+
:dedent: 4
79+
:linenos:
80+
```
81+
82+
:::

‎doc/howtos/column.md

+28
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,28 @@
1+
# Column Type
2+
3+
The Column type provides the structure and organization for storing and
4+
retrieving columnar data within HeavyDB.
5+
6+
## Basic usage
7+
8+
```{literalinclude} ../../rbc/tests/heavydb/test_howtos.py
9+
:language: python
10+
:caption: from ``test_column_power`` of ``rbc/tests/heavydb/test_howtos.py``
11+
:start-after: magictoken.udtf.column.basic.begin
12+
:end-before: magictoken.udtf.column.basic.end
13+
:dedent: 4
14+
:linenos:
15+
```
16+
17+
:::{dropdown} Example SQL Query
18+
19+
```{literalinclude} ../../rbc/tests/heavydb/test_howtos.py
20+
:language: python
21+
:caption: from ``test_column`` of ``rbc/tests/heavydb/test_howtos.py``
22+
:start-after: magictoken.udtf.column.basic.sql.begin
23+
:end-before: magictoken.udtf.column.basic.sql.end
24+
:dedent: 4
25+
:linenos:
26+
```
27+
28+
:::

‎doc/howtos/connect.md

+12
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,12 @@
1+
2+
(heavydb-connect)=
3+
# Connect to the HeavyDB server
4+
5+
```{literalinclude} ../../rbc/tests/heavydb/test_howtos.py
6+
:language: python
7+
:caption: from ``test_connect`` of ``rbc/tests/heavydb/test_howtos.py``
8+
:start-after: magictoken.connect.begin
9+
:end-before: magictoken.connect.end
10+
:dedent: 4
11+
:linenos:
12+
```

‎doc/howtos/devices.md

+25
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,25 @@
1+
# Restricting a function to run only in a specific device (CPU/GPU)
2+
3+
Assuming you already have a [connection](heavydb-connect) to the HeavyDB server:
4+
5+
```{literalinclude} ../../rbc/tests/heavydb/test_howtos.py
6+
:language: python
7+
:caption: from ``test_devices`` of ``rbc/tests/heavydb/test_howtos.py``
8+
:start-after: magictoken.devices.begin
9+
:end-before: magictoken.devices.end
10+
:dedent: 4
11+
:linenos:
12+
```
13+
14+
By default, both devices are used if available. Otherwise, only the CPU is used.
15+
16+
:::{dropdown} Example SQL Query
17+
```{literalinclude} ../../rbc/tests/heavydb/test_howtos.py
18+
:language: python
19+
:caption: from ``test_devices`` of ``rbc/tests/heavydb/test_howtos.py``
20+
:start-after: magictoken.devices.sql.begin
21+
:end-before: magictoken.devices.sql.end
22+
:dedent: 4
23+
:linenos:
24+
```
25+
:::

‎doc/howtos/external_functions.md

+52
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,52 @@
1+
2+
# Defining and using external functions
3+
4+
## cmath `abs`
5+
6+
The `external` keyword provides a way of calling C functions defined in other
7+
libraries within Python code.
8+
9+
```{literalinclude} ../../rbc/tests/heavydb/test_howtos.py
10+
:language: python
11+
:caption: from ``test_external_functions`` of ``rbc/tests/heavydb/test_howtos.py``
12+
:start-after: magictoken.external_functions.abs.begin
13+
:end-before: magictoken.external_functions.abs.end
14+
:dedent: 4
15+
:linenos:
16+
```
17+
18+
:::{dropdown} Example SQL Query
19+
```{literalinclude} ../../rbc/tests/heavydb/test_howtos.py
20+
:language: python
21+
:caption: from ``test_external_functions`` of ``rbc/tests/heavydb/test_howtos.py``
22+
:start-after: magictoken.external_functions.abs.sql.begin
23+
:end-before: magictoken.external_functions.abs.sql.end
24+
:dedent: 4
25+
:linenos:
26+
```
27+
:::
28+
29+
RBC already exposes a small set of C functions from the C stdlib. Check the API
30+
reference page for more details.
31+
32+
## Using `printf`
33+
34+
```{literalinclude} ../../rbc/tests/heavydb/test_howtos.py
35+
:language: python
36+
:caption: from ``test_external_functions`` of ``rbc/tests/heavydb/test_howtos.py``
37+
:start-after: magictoken.external_functions.printf.begin
38+
:end-before: magictoken.external_functions.printf.end
39+
:dedent: 4
40+
:linenos:
41+
```
42+
43+
:::{dropdown} Example SQL Query
44+
```{literalinclude} ../../rbc/tests/heavydb/test_howtos.py
45+
:language: python
46+
:caption: from ``test_external_functions`` of ``rbc/tests/heavydb/test_howtos.py``
47+
:start-after: magictoken.external_functions.printf.sql.begin
48+
:end-before: magictoken.external_functions.printf.sql.end
49+
:dedent: 4
50+
:linenos:
51+
```
52+
:::

‎doc/howtos/geo.md

+58
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,58 @@
1+
# Geometry Types
2+
3+
HeavyDB offers an extensive range of geometry types, encompassing
4+
`(Multi)Point`, `(Multi)LineString`, and `(Multi)Polygon`.
5+
6+
## Basics
7+
8+
### `GeoPoint`
9+
10+
```{literalinclude} ../../rbc/tests/heavydb/test_howtos.py
11+
:language: python
12+
:caption: from ``test_geopoint`` of ``rbc/tests/heavydb/test_howtos.py``
13+
:start-after: magictoken.udtf.geopoint.basic.begin
14+
:end-before: magictoken.udtf.geopoint.basic.end
15+
:dedent: 4
16+
:linenos:
17+
```
18+
19+
:::{dropdown} Example SQL Query
20+
21+
```{literalinclude} ../../rbc/tests/heavydb/test_howtos.py
22+
:language: python
23+
:caption: from ``test_geopoint`` of ``rbc/tests/heavydb/test_howtos.py``
24+
:start-after: magictoken.udtf.geopoint.basic.sql.begin
25+
:end-before: magictoken.udtf.geopoint.basic.sql.end
26+
:dedent: 4
27+
:linenos:
28+
```
29+
30+
:::
31+
32+
33+
### `GeoMultiPoint`
34+
35+
`MultiPoint` works a bit different than `Point`. They are created by calling
36+
the `.from_coords` method.
37+
38+
```{literalinclude} ../../rbc/tests/heavydb/test_howtos.py
39+
:language: python
40+
:caption: from ``test_geomultipoint`` of ``rbc/tests/heavydb/test_howtos.py``
41+
:start-after: magictoken.udtf.mp.basic.begin
42+
:end-before: magictoken.udtf.mp.basic.end
43+
:dedent: 4
44+
:linenos:
45+
```
46+
47+
:::{dropdown} Example SQL Query
48+
49+
```{literalinclude} ../../rbc/tests/heavydb/test_howtos.py
50+
:language: python
51+
:caption: from ``test_geopoint`` of ``rbc/tests/heavydb/test_howtos.py``
52+
:start-after: magictoken.udtf.mp.basic.sql.begin
53+
:end-before: magictoken.udtf.mp.basic.sql.end
54+
:dedent: 4
55+
:linenos:
56+
```
57+
58+
:::

0 commit comments

Comments
 (0)