From bc9162097130006897938d8733d93b7bf80fe9dd Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Cosmin=20=C8=98tefan=20Ciocan?=
 <57830279+cosminc98@users.noreply.github.com>
Date: Fri, 26 Jan 2024 16:22:29 +0000
Subject: [PATCH] Add new page to documentation that contains a new notebook
 that explains compiling with external libraries

---
 docs/source/index.rst     |  1 +
 docs/source/magics.rst    |  8 ++++++++
 docs/source/notebooks.rst | 34 ++++++++++++++++++++++++++++++++++
 3 files changed, 43 insertions(+)
 create mode 100644 docs/source/notebooks.rst

diff --git a/docs/source/index.rst b/docs/source/index.rst
index 1f07bdd..3ed1746 100644
--- a/docs/source/index.rst
+++ b/docs/source/index.rst
@@ -10,4 +10,5 @@ which provides CUDA capable GPUs with the CUDA toolkit already installed.
    :caption: Contents:
 
    usage
+   notebooks
    magics
diff --git a/docs/source/magics.rst b/docs/source/magics.rst
index 58823a5..28a3bf1 100644
--- a/docs/source/magics.rst
+++ b/docs/source/magics.rst
@@ -27,19 +27,27 @@ Usage
 Options
 -------
 
+.. _timeit:
+
 -t, --timeit
    Boolean. If set, returns the output of the "timeit" built-in
    ipython magic instead of stdout.
 
+.. _profile:
+
 -p, --profile
    Boolean. If set, runs the NVIDIA Nsight Compute profiler whose
    output is appended to standard output.
 
+.. _profiler_args:
+
 -a, --profiler-args
    String. Optional profiler arguments that can be space separated
    by wrapping them in double quotes. See all options here:
    `Nsight Compute CLI <https://docs.nvidia.com/nsight-compute/NsightComputeCli/index.html#command-line-options>`_
 
+.. _compiler_args:
+
 -c, --compiler-args
    String. Optional compiler arguments that can be space separated
    by wrapping them in double quotes. They will be passed to "nvcc".
diff --git a/docs/source/notebooks.rst b/docs/source/notebooks.rst
new file mode 100644
index 0000000..a662ef4
--- /dev/null
+++ b/docs/source/notebooks.rst
@@ -0,0 +1,34 @@
+*********
+Notebooks
+*********
+
+This page provides a list of useful Jupyter notebooks written with the
+**nvcc4jupyter** library.
+
+.. note::
+   These notebooks are written for Google's Colab, but you may run them in
+   other environments by installing all expected dependencies. If running in
+   Colab, make sure to set the runtime type to a GPU instance (at the time of
+   writing this, T4 is the GPU offered for free by Colab).
+
+------
+
+.. _compiling_with_external_libraries:
+
+Compiling with external libraries
+=================================
+
+[`NOTEBOOK <https://colab.research.google.com/drive/1iuY46DCwv4hy3SqDhJgFeO8kgpHnzjTh?usp=sharing>`_]
+
+If you need to compile CUDA C++ code that uses external libraries in the host
+code (e.g. OpenCV for reading and writing images to disk) then this section is
+for you.
+
+To achieve this, use the :ref:`compiler-args <compiler_args>` option of the
+:ref:`cuda <cuda_magic>` magic command to pass the correct compiler options
+of the OpenCV library to **nvcc** for it to link the OpenCV code with the
+code in your Jupyter cell. Those compiler options can be provided by the
+`pkg-config <https://www.freedesktop.org/wiki/Software/pkg-config/>`_ tool.
+
+In the notebook we show how to use OpenCV to load an image, blur it with a CUDA
+kernel, and then save it back to disk using OpenCV again.