[doc] content and build.yml

flatironinstitute · Feb 10, 2024 · 4600944 · 4600944
1 parent 3ec9b08
commit 4600944
Show file tree

Hide file tree

Showing 12 changed files with 237 additions and 49 deletions.
diff --git a/.github/workflows/build.yml b/.github/workflows/build.yml
@@ -13,53 +13,73 @@ jobs:
       fail-fast: false
       matrix:
         include:
-          - {os: ubuntu-18.04, cc: clang-11, cxx: clang++-11}
-          - {os: ubuntu-20.04, cc: clang-10, cxx: clang++-10}
-          - {os: ubuntu-20.04, cc: clang-11, cxx: clang++-11}
-            #- {os: macos-10.15, cc: /usr/local/opt/llvm/bin/clang, cxx: /usr/local/opt/llvm/bin/clang++}
+          - {os: ubuntu-22.04, cc: clang-15, cxx: clang++-15, doc: ON}
+            #- {os: ubuntu-20.04, cc: clang-11, cxx: clang++-11}
+            #- {os: macos-14, cc: /usr/local/opt/llvm/bin/clang, cxx: /usr/local/opt/llvm/bin/clang++, doc: OFF}
 
     runs-on: ${{ matrix.os }}
 
     steps:
-    - uses: actions/checkout@v2
+    - uses: actions/checkout@v4
 
-    - name: Install ubuntu 20.04 clang-10 dependencies
-      if: matrix.os == 'ubuntu-20.04' && matrix.cc == 'clang-10'
+    - uses: actions/cache/restore@v3
+      with:
+        path: ${{ env.CCACHE_DIR }}
+        key: ccache-${{ matrix.os }}-${{ matrix.cc }}-${{ github.run_id }}
+        restore-keys:
+          ccache-${{ matrix.os }}-${{ matrix.cc }}-
+
+    - name: Install ubuntu dependencies
+      if: matrix.os == 'ubuntu-22.04'
       run: >
         sudo apt-get update &&
         sudo apt-get install
-        clang-10
-        clang-tools-10
-        libclang-10-dev
-        libhdf5-dev
+        ccache
+        clang-15
+        libblas-dev
+        libc++-15-dev
+        libc++abi-15-dev
+        libomp-15-dev
+        python3
         python3-dev
         python3-numpy
-
-    - name: Install dependencies for ubuntu 18.04 and 20.04 builds with clang-11
-      if: (matrix.os == 'ubuntu-18.04' || matrix.os == 'ubuntu-20.04') && matrix.cc == 'clang-11'
-      run: |
-        sudo bash -c "$(wget -O - https://apt.llvm.org/llvm.sh)"
-        sudo apt-get install libclang-11-dev libhdf5-dev python3-dev python3-numpy
+        python3-pip
+        &&
+        pip3 install myst-parser linkify-it-py &&
+        pip3 install sphinx==5.3.0 sphinx-rtd-theme
 
     - name: Install homebrew dependencies
-      if: matrix.os == 'macos-10.15'
+      if: matrix.os == 'macos-14'
       run: |
-        brew install llvm hdf5
+        brew install llvm [email protected] 
         pip3 install numpy
 
+    - name: add clang cxxflags
+      if: ${{ contains(matrix.cxx, 'clang') }}
+      run:
+        echo "CXXFLAGS=-stdlib=libc++" >> $GITHUB_ENV
+
     - name: Build clair
       env:
         CC: ${{ matrix.cc }}
         CXX: ${{ matrix.cxx }}
         LIBRARY_PATH: /usr/local/opt/llvm/lib
-        CMAKE_PREFIX_PATH: /usr/lib/llvm-11/lib/cmake/clang:/usr/lib/llvm-10/lib/cmake/clang
       run: |
-        mkdir build && cmake -B build -DCMAKE_INSTALL_PREFIX=/opt/clair
-        cmake --build build -j2
+        cmake -B build -S. -DCMAKE_INSTALL_PREFIX=$HOME/install -DBuild_Documentation=${{ matrix.doc }}
+        make -j2 || make -j1 VERBOSE=1
 
     - name: Test clair
       env:
         DYLD_FALLBACK_LIBRARY_PATH: /usr/local/opt/llvm/lib
       run: |
         cd build
         ctest -j2 --output-on-failure
+
+    - name: Deploy documentation to website
+      if: matrix.doc == 'ON' && github.ref == 'refs/heads/main'
+      uses: JamesIves/github-pages-deploy-action@v4
+      with:
+        folder: build/doc/html
+        branch: github.io
+        target-folder: docs/main
+
diff --git a/doc/ChangeLog.md b/doc/ChangeLog.md
@@ -0,0 +1,4 @@
+(changelog)=
+
+# Changelog
+
diff --git a/doc/about.rst b/doc/about.rst
@@ -1,5 +1,5 @@
 .. _about:
 
-About clair/cpy2
+About clair/c2py
 ****************
 
diff --git a/doc/conf.py.in b/doc/conf.py.in
@@ -10,14 +10,15 @@ sys.path.insert(0, "@CMAKE_CURRENT_SOURCE_DIR@/sphinxext/numpydoc")
 exclude_patterns = ['_templates']
 
 extensions = ['sphinx.ext.autodoc',
-              'sphinx.ext.mathjax',
-              'sphinx.ext.intersphinx',
-              'sphinx.ext.doctest',
+              #'sphinx.ext.mathjax',
+              #'sphinx.ext.intersphinx',
+              #'sphinx.ext.doctest',
               'sphinx.ext.todo',
               'sphinx.ext.viewcode',
               'sphinx.ext.autosummary',
               'sphinx.ext.githubpages',
-              #'nbsphinx',
+              # 'nbsphinx',
+               'myst_parser',
               ]
 
 # The name of the Pygments (syntax highlighting) style to use.

diff --git a/doc/gettingstarted.rst b/doc/gettingstarted.rst
@@ -17,10 +17,10 @@ We just compile the C++ file with `clang` using the ``clair`` plugin as
 .. code-block:: bash
    
    # OS X
-   clang++ -fplugin=clair_c2py.dylib `c2py_flags` my_module.cpp -std=c++20 -shared -o my_module.so
+   clang++ -fplugin=clair_c2py.dylib  my_module.cpp -std=c++20 -shared -o my_module.so `c2py_flags`
    
    # Linux
-   clang++ -fplugin=clair_c2py.so    `c2py_flags` my_module.cpp -std=c++20 -shared -o my_module.so
+   clang++ -fplugin=clair_c2py.so     my_module.cpp -std=c++20 -shared -o my_module.so `c2py_flags`
 
 
 That is it. The Python module is ready to use:
@@ -80,7 +80,7 @@ they can reused with any `C++20` compiler. For example, with ``gcc``.
 
 .. code-block:: bash
 
-   g++ `c2py_flags` my_module.wrap.cxx -std=c++20 -shared -o my_module.so
+   g++  my_module.wrap.cxx -std=c++20 -shared -o my_module.so `c2py_flags`
 
 
 (the bindings automatically include the original source file `my_module.cpp`).

diff --git a/doc/index.rst b/doc/index.rst
@@ -5,8 +5,9 @@ clair/c2y
 
 .. sidebar:: clair |PROJECT_VERSION|
 
-   This is the homepage of clair/c2py|PROJECT_VERSION|.
-   For changes see the :ref:`changelog page <changelog>`.
+   This is the homepage of clair/c2py |PROJECT_VERSION|.
+
+   For changes see the :ref:`changelog page <ChangeLog>`.
 
       .. image:: _static/logo_github.png
          :width: 75%
@@ -26,4 +27,5 @@ clair/c2y
    reference
    notebook
    issues
+   ChangeLog
    about
diff --git a/doc/install.rst b/doc/install.rst
@@ -8,20 +8,16 @@ Installation
 Clair/c2py is made of two components:
 
 
-* **c2py**
+* `c2py <https://github.com/flatironinstitute/c2py>`_
 
-  Low level C++20 support library for the bindings.
-
-  It depends only on Python/Numpy C API and can be used with any C++20 compliant compilers 
-  (NB : currently tested on clang >=16 and gcc >=12). 
-
-* **clair** 
+   Low level C++20 support library for the bindings.
+   It depends only on Python/Numpy C API and can be used with any C++20 compliant compilers (NB : currently tested on clang >=16 and gcc >=12). 
 
-  A collection of Clang plugins. 
+* `Clair <https://github.com/flatironinstitute/clair>`_
 
-  Clair/c2py plugin generates the Python bindings automatically from the C++ source.
-
-  Can only be used with LLVM/clang and with the *exact version of clang for which it has been compiled*. 
+   | A collection of Clang plugins. 
+   | Clair/c2py plugin generates the Python bindings automatically from the C++ source.
+   | Can only be used with LLVM/clang and with the *exact version of clang for which it has been compiled*. 
  
 
 

diff --git a/doc/install_packages.rst b/doc/install_packages.rst
@@ -14,7 +14,12 @@ Experimental packages of ``c2py`` and ``clair`` are::
 
 They are built from source from the GitHub parcollet/ccq repository.
 
-.. warning::
+.. note::
 
-   RECHECK it works
+   The DYLD_LIBRARY_PATH must be set e.g.::
+
+     export DYLD_LIBRARY_PATH=/opt/homebrew/lib/:$DYLD_LIBRARY_PATH
+
+   for clang to find its plugins in brew directory as in the documentation examples.
+
 
diff --git a/doc/notebook.rst b/doc/notebook.rst
@@ -7,10 +7,10 @@ Clair defines a IPython notebook magic cell ``%%c2py``
 to compile C++ code from a notebook cell.
 
 
-..  .. toctree::
+.... toctree::
    ..:maxdepth: 2
    ..:caption: Contents:
 
-   ..notebooks/C2pyMagicDemo
+   ..notebooks/C2pyMagicDemo.ipynb
 
 
diff --git a/doc/notebooks/C2pyMagicDemo.ipynb b/doc/notebooks/C2pyMagicDemo.ipynb
@@ -0,0 +1,160 @@
+{
+ "cells": [
+  {
+   "cell_type": "code",
+   "execution_count": 1,
+   "id": "eb187f68-7c62-4561-89a4-d8f0d10c2f32",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "%load_ext clair.c2py_magic"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": 5,
+   "id": "7f1865b8-2ff3-459b-806b-58a21dbb124b",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "%%c2py \n",
+    "// C++\n",
+    "int add(int i, int j) { \n",
+    " return i+j;\n",
+    "}"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": 8,
+   "id": "2a36f64c-0a85-4d83-880e-1bcd2fe6d75d",
+   "metadata": {},
+   "outputs": [
+    {
+     "ename": "TypeError",
+     "evalue": "[c2py] Can not call the function with the arguments\n  - (1, '2')\nThe dispatch to C++ failed with the following error(s):\n[1] (i: int, j: int) -> int \n    j: Cannot convert 2 to integer type\n",
+     "output_type": "error",
+     "traceback": [
+      "\u001b[0;31m---------------------------------------------------------------------------\u001b[0m",
+      "\u001b[0;31mTypeError\u001b[0m                                 Traceback (most recent call last)",
+      "Cell \u001b[0;32mIn[8], line 2\u001b[0m\n\u001b[1;32m      1\u001b[0m \u001b[38;5;66;03m# Python\u001b[39;00m\n\u001b[0;32m----> 2\u001b[0m \u001b[38;5;28mprint\u001b[39m(\u001b[43madd\u001b[49m\u001b[43m(\u001b[49m\u001b[38;5;241;43m1\u001b[39;49m\u001b[43m,\u001b[49m\u001b[38;5;124;43m\"\u001b[39;49m\u001b[38;5;124;43m2\u001b[39;49m\u001b[38;5;124;43m\"\u001b[39;49m\u001b[43m)\u001b[49m)\n",
+      "\u001b[0;31mTypeError\u001b[0m: [c2py] Can not call the function with the arguments\n  - (1, '2')\nThe dispatch to C++ failed with the following error(s):\n[1] (i: int, j: int) -> int \n    j: Cannot convert 2 to integer type\n"
+     ]
+    }
+   ],
+   "source": [
+    "# Python\n",
+    "print(add(1,\"2\"))"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "a1483b25-4deb-4673-91df-72444c8c4fa7",
+   "metadata": {},
+   "outputs": [],
+   "source": []
+  },
+  {
+   "cell_type": "code",
+   "execution_count": 7,
+   "id": "cbe93901-f798-4238-8e83-1400098bbcb9",
+   "metadata": {},
+   "outputs": [
+    {
+     "name": "stdout",
+     "output_type": "stream",
+     "text": [
+      "Error: \n",
+      "\u001b[1m[Cell].cpp:3:8: \u001b[0m\u001b[0;1;31merror: \u001b[0m\u001b[1munknown type name 'bad'\u001b[0m\n",
+      "    3 | void f(bad x) { }\u001b[0m\n",
+      "      | \u001b[0;1;32m       ^\n",
+      "\u001b[0m1 error generated.\n",
+      "\n"
+     ]
+    },
+    {
+     "ename": "RuntimeError",
+     "evalue": "Error in executing command: \n export DYLD_LIBRARY_PATH=/Users/oparcollet/clair_install/lib::$DYLD_LIBRARY_PATH\n\nclang++ -fplugin=clair_c2py.dylib `c2py_flags` -std=c++20 -shared -o c2py_ipython_magic_cd48fb3c7b197b57cf0f96970d60b1ca.so c2py_ipython_magic_cd48fb3c7b197b57cf0f96970d60b1ca.cpp -fdiagnostics-color=always  ",
+     "output_type": "error",
+     "traceback": [
+      "\u001b[0;31m---------------------------------------------------------------------------\u001b[0m",
+      "\u001b[0;31mRuntimeError\u001b[0m                              Traceback (most recent call last)",
+      "Cell \u001b[0;32mIn[7], line 1\u001b[0m\n\u001b[0;32m----> 1\u001b[0m \u001b[43mget_ipython\u001b[49m\u001b[43m(\u001b[49m\u001b[43m)\u001b[49m\u001b[38;5;241;43m.\u001b[39;49m\u001b[43mrun_cell_magic\u001b[49m\u001b[43m(\u001b[49m\u001b[38;5;124;43m'\u001b[39;49m\u001b[38;5;124;43mc2py\u001b[39;49m\u001b[38;5;124;43m'\u001b[39;49m\u001b[43m,\u001b[49m\u001b[43m \u001b[49m\u001b[38;5;124;43m'\u001b[39;49m\u001b[38;5;124;43m'\u001b[39;49m\u001b[43m,\u001b[49m\u001b[43m \u001b[49m\u001b[38;5;124;43m'\u001b[39;49m\u001b[38;5;124;43mvoid f(bad x) \u001b[39;49m\u001b[38;5;124;43m{\u001b[39;49m\u001b[38;5;124;43m }\u001b[39;49m\u001b[38;5;130;43;01m\\n\u001b[39;49;00m\u001b[38;5;124;43m'\u001b[39;49m\u001b[43m)\u001b[49m\n",
+      "File \u001b[0;32m/opt/homebrew/opt/ipython/libexec/lib/python3.12/site-packages/IPython/core/interactiveshell.py:2517\u001b[0m, in \u001b[0;36mInteractiveShell.run_cell_magic\u001b[0;34m(self, magic_name, line, cell)\u001b[0m\n\u001b[1;32m   2515\u001b[0m \u001b[38;5;28;01mwith\u001b[39;00m \u001b[38;5;28mself\u001b[39m\u001b[38;5;241m.\u001b[39mbuiltin_trap:\n\u001b[1;32m   2516\u001b[0m     args \u001b[38;5;241m=\u001b[39m (magic_arg_s, cell)\n\u001b[0;32m-> 2517\u001b[0m     result \u001b[38;5;241m=\u001b[39m \u001b[43mfn\u001b[49m\u001b[43m(\u001b[49m\u001b[38;5;241;43m*\u001b[39;49m\u001b[43margs\u001b[49m\u001b[43m,\u001b[49m\u001b[43m \u001b[49m\u001b[38;5;241;43m*\u001b[39;49m\u001b[38;5;241;43m*\u001b[39;49m\u001b[43mkwargs\u001b[49m\u001b[43m)\u001b[49m\n\u001b[1;32m   2519\u001b[0m \u001b[38;5;66;03m# The code below prevents the output from being displayed\u001b[39;00m\n\u001b[1;32m   2520\u001b[0m \u001b[38;5;66;03m# when using magics with decorator @output_can_be_silenced\u001b[39;00m\n\u001b[1;32m   2521\u001b[0m \u001b[38;5;66;03m# when the last Python token in the expression is a ';'.\u001b[39;00m\n\u001b[1;32m   2522\u001b[0m \u001b[38;5;28;01mif\u001b[39;00m \u001b[38;5;28mgetattr\u001b[39m(fn, magic\u001b[38;5;241m.\u001b[39mMAGIC_OUTPUT_CAN_BE_SILENCED, \u001b[38;5;28;01mFalse\u001b[39;00m):\n",
+      "File \u001b[0;32m~/clair_install/lib/python3.12/site-packages/clair/c2py_magic.py:72\u001b[0m, in \u001b[0;36mC2pyMagics.c2py\u001b[0;34m(self, line, cell)\u001b[0m\n\u001b[1;32m     69\u001b[0m args \u001b[38;5;241m=\u001b[39m magic_arguments\u001b[38;5;241m.\u001b[39mparse_argstring(\u001b[38;5;28mself\u001b[39m\u001b[38;5;241m.\u001b[39mc2py, line)\n\u001b[1;32m     71\u001b[0m code \u001b[38;5;241m=\u001b[39m cell \u001b[38;5;28;01mif\u001b[39;00m cell\u001b[38;5;241m.\u001b[39mendswith(\u001b[38;5;124m'\u001b[39m\u001b[38;5;130;01m\\n\u001b[39;00m\u001b[38;5;124m'\u001b[39m) \u001b[38;5;28;01melse\u001b[39;00m cell \u001b[38;5;241m+\u001b[39m \u001b[38;5;124m'\u001b[39m\u001b[38;5;130;01m\\n\u001b[39;00m\u001b[38;5;124m'\u001b[39m\n\u001b[0;32m---> 72\u001b[0m module \u001b[38;5;241m=\u001b[39m \u001b[38;5;28;43mcompile\u001b[39;49m\u001b[43m(\u001b[49m\u001b[43mcode\u001b[49m\u001b[43m,\u001b[49m\u001b[43m \u001b[49m\u001b[43mcompile_instruction_name\u001b[49m\u001b[43m \u001b[49m\u001b[38;5;241;43m=\u001b[39;49m\u001b[43m \u001b[49m\u001b[43margs\u001b[49m\u001b[38;5;241;43m.\u001b[39;49m\u001b[43mcompile\u001b[49m\u001b[43m,\u001b[49m\u001b[43m \u001b[49m\u001b[43mverbosity\u001b[49m\u001b[43m \u001b[49m\u001b[38;5;241;43m=\u001b[39;49m\u001b[43m \u001b[49m\u001b[43margs\u001b[49m\u001b[38;5;241;43m.\u001b[39;49m\u001b[43mverbosity\u001b[49m\u001b[43m,\u001b[49m\u001b[43m \u001b[49m\u001b[43mrecompile\u001b[49m\u001b[43m \u001b[49m\u001b[38;5;241;43m=\u001b[39;49m\u001b[43m \u001b[49m\u001b[38;5;28;43;01mTrue\u001b[39;49;00m\u001b[43m)\u001b[49m\n\u001b[1;32m     74\u001b[0m \u001b[38;5;66;03m# import all object and function in the main namespace\u001b[39;00m\n\u001b[1;32m     75\u001b[0m imported \u001b[38;5;241m=\u001b[39m []\n",
+      "File \u001b[0;32m~/clair_install/lib/python3.12/site-packages/clair/compiler.py:92\u001b[0m, in \u001b[0;36mcompile\u001b[0;34m(code, verbosity, compile_instruction_name, only, cxxflags, moduledir, recompile, no_clean)\u001b[0m\n\u001b[1;32m     90\u001b[0m     cmd_for_machine \u001b[38;5;241m=\u001b[39m cmd\u001b[38;5;241m.\u001b[39mformat(m \u001b[38;5;241m=\u001b[39m module_name)\n\u001b[1;32m     91\u001b[0m     cmd_for_log \u001b[38;5;241m=\u001b[39m \u001b[38;5;124m\"\u001b[39m\u001b[38;5;124mCompilation command: \u001b[39m\u001b[38;5;124m\"\u001b[39m \u001b[38;5;241m+\u001b[39m cmd\u001b[38;5;241m.\u001b[39mformat(m \u001b[38;5;241m=\u001b[39m \u001b[38;5;124m\"\u001b[39m\u001b[38;5;124m[Cell]\u001b[39m\u001b[38;5;124m\"\u001b[39m) \u001b[38;5;241m+\u001b[39m \u001b[38;5;124m'\u001b[39m\u001b[38;5;130;01m\\n\u001b[39;00m\u001b[38;5;124m'\u001b[39m\n\u001b[0;32m---> 92\u001b[0m     \u001b[43mexecute\u001b[49m\u001b[43m \u001b[49m\u001b[43m(\u001b[49m\u001b[43mcmd_for_machine\u001b[49m\u001b[43m,\u001b[49m\u001b[43m \u001b[49m\u001b[43mcmd_for_log\u001b[49m\u001b[43m \u001b[49m\u001b[38;5;28;43;01mif\u001b[39;49;00m\u001b[43m \u001b[49m\u001b[43mverbosity\u001b[49m\u001b[43m \u001b[49m\u001b[38;5;28;43;01melse\u001b[39;49;00m\u001b[43m \u001b[49m\u001b[38;5;124;43m\"\u001b[39;49m\u001b[38;5;124;43m\"\u001b[39;49m\u001b[43m,\u001b[49m\u001b[43m \u001b[49m\u001b[43m{\u001b[49m\u001b[43mmodule_name\u001b[49m\u001b[43m:\u001b[49m\u001b[38;5;124;43m\"\u001b[39;49m\u001b[38;5;124;43m[Cell]\u001b[39;49m\u001b[38;5;124;43m\"\u001b[39;49m\u001b[43m,\u001b[49m\u001b[43m \u001b[49m\u001b[43mmodule_dirname\u001b[49m\u001b[43m:\u001b[49m\u001b[38;5;124;43m\"\u001b[39;49m\u001b[38;5;124;43m\"\u001b[39;49m\u001b[43m}\u001b[49m\u001b[43m)\u001b[49m\n\u001b[1;32m     94\u001b[0m \u001b[38;5;28;01mexcept\u001b[39;00m: \u001b[38;5;66;03m# we clean if fail\u001b[39;00m\n\u001b[1;32m     95\u001b[0m     os\u001b[38;5;241m.\u001b[39mchdir(old_cwd)\n",
+      "File \u001b[0;32m~/clair_install/lib/python3.12/site-packages/clair/compiler.py:20\u001b[0m, in \u001b[0;36mexecute\u001b[0;34m(command, message, replacements)\u001b[0m\n\u001b[1;32m     18\u001b[0m        err \u001b[38;5;241m=\u001b[39m err\u001b[38;5;241m.\u001b[39mreplace(k,v)\n\u001b[1;32m     19\u001b[0m    print_out (\u001b[38;5;124m\"\u001b[39m\u001b[38;5;124mError: \u001b[39m\u001b[38;5;130;01m\\n\u001b[39;00m\u001b[38;5;124m\"\u001b[39m \u001b[38;5;241m+\u001b[39m message, err)\n\u001b[0;32m---> 20\u001b[0m \u001b[38;5;28;01mraise\u001b[39;00m \u001b[38;5;167;01mRuntimeError\u001b[39;00m(\u001b[38;5;124m\"\u001b[39m\u001b[38;5;124mError in executing command: \u001b[39m\u001b[38;5;130;01m\\n\u001b[39;00m\u001b[38;5;124m \u001b[39m\u001b[38;5;132;01m%s\u001b[39;00m\u001b[38;5;124m\"\u001b[39m\u001b[38;5;241m%\u001b[39mcommand)\n",
+      "\u001b[0;31mRuntimeError\u001b[0m: Error in executing command: \n export DYLD_LIBRARY_PATH=/Users/oparcollet/clair_install/lib::$DYLD_LIBRARY_PATH\n\nclang++ -fplugin=clair_c2py.dylib `c2py_flags` -std=c++20 -shared -o c2py_ipython_magic_cd48fb3c7b197b57cf0f96970d60b1ca.so c2py_ipython_magic_cd48fb3c7b197b57cf0f96970d60b1ca.cpp -fdiagnostics-color=always  "
+     ]
+    }
+   ],
+   "source": [
+    "%%c2py \n",
+    "void f(bad x) { }"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "198c41ae-146b-4fd3-8127-16648b4ba93e",
+   "metadata": {},
+   "outputs": [],
+   "source": []
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "c4568ccc-982e-4fce-8087-2b9d7c0282e4",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "%%c2py \n",
+    "int * g(int x) { return new int[10]; }"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "6a5bdceb-338b-453f-ae1a-2a9a8ce37b8f",
+   "metadata": {},
+   "outputs": [],
+   "source": []
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "dec01f25-26cc-4be5-bcff-663afd276c44",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "%%c2py \n",
+    "int add(int i, int j) { \n",
+    " throw std::runtime_error(\"AIE !\");\n",
+    " return i+j;\n",
+    "}"
+   ]
+  }
+ ],
+ "metadata": {
+  "kernelspec": {
+   "display_name": "Python 3 (ipykernel)",
+   "language": "python",
+   "name": "python3"
+  },
+  "language_info": {
+   "codemirror_mode": {
+    "name": "ipython",
+    "version": 3
+   },
+   "file_extension": ".py",
+   "mimetype": "text/x-python",
+   "name": "python",
+   "nbconvert_exporter": "python",
+   "pygments_lexer": "ipython3",
+   "version": "3.12.1"
+  }
+ },
+ "nbformat": 4,
+ "nbformat_minor": 5
+}
diff --git a/doc/reference.rst b/doc/reference.rst
@@ -6,7 +6,7 @@ Reference documentation
 .. toctree::
    :maxdepth: 2
 
-   reference/config
+   reference/customize
    reference/fnt_basic
    reference/classes
    reference/enums