diff --git a/docs/source/api_reference/warpbyscalar.rst b/docs/source/api_reference/warpbyscalar.rst
new file mode 100644
index 0000000..dd1e9c4
--- /dev/null
+++ b/docs/source/api_reference/warpbyscalar.rst
@@ -0,0 +1,50 @@
+WarpByScalar
+============
+
+The ``WarpByScalar`` widget will modify the mesh geometry.
+
+It is similar to ``Paraview``, ``PyVista`` and ``vtk``'s warp-by-scalar effect, but instead of computing the transformation on the CPU,
+it is entirely computed on the GPU. Which means that changing the warp factor does not involve looping over the mesh vertices,
+we only send the new ``factor`` value to the GPU.
+
+The ``input`` attribute should be a 1-D data. For example, if your mesh has a 1-D ``Data`` named ``"height"``, your can set the input to be:
+
+.. code::
+
+    warped_mesh = WarpByScalar(mesh, input='height')  # Warp by 'height' data
+
+
+Examples
+--------
+
+.. code:: Python
+
+    from pyvista import examples
+    import numpy as np
+
+    from ipywidgets import VBox, FloatSlider
+    from ipygany import PolyMesh, Scene, IsoColor, WarpByScalar
+
+    pvmesh = examples.download_topo_global()
+    ugrid = pvmesh.cast_to_unstructured_grid()
+
+    from ipygany import PolyMesh, Scene, IsoColor, WarpByScalar
+
+    # Turn the PyVista mesh into a PolyMesh
+    mesh = PolyMesh.from_vtk(ugrid)
+
+    colored_mesh = IsoColor(mesh, min=-10421.0, max=6527.0)
+    warped_mesh = WarpByScalar(colored_mesh, input='altitude', factor=0.5e-5)
+
+    # Link a slider to the warp value
+    warp_slider = FloatSlider(min=0., max=5., value=0.5)
+
+    def on_slider_change(change):
+        warped_mesh.factor = change['new'] * 1e-5
+
+    warp_slider.observe(on_slider_change, 'value')
+
+    VBox((warp_slider, Scene([warped_mesh])))
+
+.. image:: warpscalar.gif
+   :alt: warpscalar
diff --git a/docs/source/api_reference/warpscalar.gif b/docs/source/api_reference/warpscalar.gif
new file mode 100644
index 0000000..679f01d
Binary files /dev/null and b/docs/source/api_reference/warpscalar.gif differ
diff --git a/docs/source/api_reference/water.rst b/docs/source/api_reference/water.rst
index 36d0e93..54e93ef 100644
--- a/docs/source/api_reference/water.rst
+++ b/docs/source/api_reference/water.rst
@@ -17,7 +17,7 @@ If you have under-water meshes on which you want to cast caustics, you need to c
 
 Then you'll need to pass those under-water meshes to the water effect:
 
-.. code::
+.. code:: Python
 
     underwater_mesh1 = UnderWater(mesh1, input='underwater')
     underwater_mesh2 = UnderWater(mesh2, input='underwater')
diff --git a/docs/source/index.rst b/docs/source/index.rst
index f2f4e71..f3de799 100644
--- a/docs/source/index.rst
+++ b/docs/source/index.rst
@@ -26,6 +26,7 @@ ipygany: Scientific visualization in the Jupyter notebook
 
     api_reference/isocolor
     api_reference/warp
+    api_reference/warpbyscalar
     api_reference/threshold
 
 .. toctree::