diff --git a/CMakeLists.txt b/CMakeLists.txt
index 4b8e0d999..85f9236df 100644
--- a/CMakeLists.txt
+++ b/CMakeLists.txt
@@ -12,6 +12,8 @@ if(NOT EXISTS ${SOURCE_DIR}/awesomeConfig.cmake)
     message(FATAL_ERROR "Please provide awesomeConfig.cmake")
 endif()
 
+# Define many variables
+
 include(awesomeConfig.cmake)
 
 include_directories(
@@ -252,8 +254,10 @@ endif()
 
 # {{{ Lua API Documentation
 if(GENERATE_DOC)
+
     if(NOT BUILD_DIR STREQUAL SOURCE_DIR)
         file(MAKE_DIRECTORY ${BUILD_DIR}/lib)
+        file(MAKE_DIRECTORY ${BUILD_DIR}/doc)
     endif()
 
     file(GLOB_RECURSE AWE_LUA_FILES ${BUILD_DIR}/lib/*.lua)
diff --git a/awesomeConfig.cmake b/awesomeConfig.cmake
index 060785a8e..33d09ff0c 100644
--- a/awesomeConfig.cmake
+++ b/awesomeConfig.cmake
@@ -295,6 +295,12 @@ set(AWESOME_ICON_PATH        ${AWESOME_DATA_PATH}/icons)
 set(AWESOME_THEMES_PATH      ${AWESOME_DATA_PATH}/themes)
 # }}}
 
+
+if(GENERATE_DOC)
+    # Generate some images and examples
+    include(docs/generate_examples.cmake)
+endif()
+
 # {{{ Configure files
 file(GLOB awesome_c_configure_files RELATIVE ${SOURCE_DIR}
     ${SOURCE_DIR}/*.c
diff --git a/docs/generate_examples.cmake b/docs/generate_examples.cmake
new file mode 100644
index 000000000..61ec092c3
--- /dev/null
+++ b/docs/generate_examples.cmake
@@ -0,0 +1,47 @@
+
+# Get and update the LUA_PATH so the scripts can be executed without Awesome
+execute_process(COMMAND lua -e print\(package.path\) OUTPUT_VARIABLE LUA_PATH_)
+set(ENV{LUA_PATH} "${SOURCE_DIR}/lib/?;${SOURCE_DIR}/lib/?.lua;${LUA_PATH_}")
+
+file(MAKE_DIRECTORY "${BUILD_DIR}/doc/images")
+
+#
+# Shape API
+#
+foreach (SHAPE_NAME "circle" "arrow" "rounded_rect" "hexagon" "infobubble"
+    "powerline" "isosceles_triangle" "cross" "octogon" "parallelogram"
+    "losange" "partially_rounded_rect" "radial_progress" "rounded_bar"
+    "rectangle" "rectangular_tag")
+    set(SHAPE_FILE "${SOURCE_DIR}/tests/shape/${SHAPE_NAME}.lua")
+    set(SHAPE_SVG  "${BUILD_DIR}/doc/images/shape_${SHAPE_NAME}.svg")
+
+    # Generate some SVG for the documentation and load the examples for the doc
+    execute_process(
+        COMMAND lua ${SOURCE_DIR}/tests/shape/test-shape.lua ${SHAPE_FILE} ${SHAPE_SVG}
+        OUTPUT_VARIABLE SHAPE_OUTPUT
+        ERROR_VARIABLE  SHAPE_ERROR
+    )
+
+    if (NOT SHAPE_ERROR STREQUAL "")
+        message(${SHAPE_ERROR})
+        message(FATAL_ERROR ${SHAPE_NAME} " SVG generation failed, bye")
+    endif()
+
+    # Set the SVG paths for the doc
+    set(SHAPE_${SHAPE_NAME}_SVG "../images/shape_${SHAPE_NAME}.svg")
+
+    # Use the .lua as code example
+    file(READ ${SHAPE_FILE} SHAPE_EXAMPLE)
+    STRING(REGEX REPLACE "\n" ";" SHAPE_EXAMPLE "${SHAPE_EXAMPLE}")
+    SET(SHAPE_COMMENTED
+        "![Shape example](../images/shape_${SHAPE_NAME}.svg)\n--\n-- @usage"
+    )
+    foreach (EXAMPLE_FILE ${SHAPE_EXAMPLE})
+        if(NOT EXAMPLE_FILE MATCHES "^.+--DOC_HIDE$")
+            SET(SHAPE_COMMENTED ${SHAPE_COMMENTED}\n--${EXAMPLE_FILE})
+        endif()
+    endforeach()
+
+    set(SHAPE_${SHAPE_NAME}_EXAMPLE ${SHAPE_COMMENTED})
+
+endforeach()
diff --git a/lib/gears/shape.lua b/lib/gears/shape.lua
index eff81489b..d2496b38e 100644
--- a/lib/gears/shape.lua
+++ b/lib/gears/shape.lua
@@ -8,8 +8,8 @@
 -- parameter followed by the widget and height and additional parameters.
 --
 -- The functions provided by this module only create a path in the content.
--- to actually draw the content, use cr:fill(), cr:mask(), cr:slip() or
--- cr:stroke()
+-- to actually draw the content, use `cr:fill()`, `cr:mask()`, `cr:clip()` or
+-- `cr:stroke()`
 --
 -- In many case, it is necessary to apply the shape using a transformation
 -- such as a rotation. The preferred way to do this is to wrap the function
@@ -27,10 +27,13 @@ local module = {}
 
 --- Add a rounded rectangle to the current path.
 -- Note: If the radius is bigger than either half side, it will be reduced.
+--
+-- @SHAPE_rounded_rect_EXAMPLE@
+--
 -- @param cr A cairo content
--- @param width The rectangle width
--- @param height The rectangle height
--- @param radius the corner radius
+-- @tparam number width The rectangle width
+-- @tparam number height The rectangle height
+-- @tparam number radius the corner radius
 function module.rounded_rect(cr, width, height, radius)
     if width / 2 < radius then
         radius = width / 2
@@ -48,7 +51,10 @@ function module.rounded_rect(cr, width, height, radius)
     cr:close_path()
 end
 
---- Add a rectangle delimited by 2 180 degree arcs to the path
+--- Add a rectangle delimited by 2 180 degree arcs to the path.
+--
+-- @SHAPE_rounded_bar_EXAMPLE@
+--
 -- @param cr A cairo content
 -- @param width The rectangle width
 -- @param height The rectangle height
@@ -56,19 +62,76 @@ function module.rounded_bar(cr, width, height)
     module.rounded_rect(cr, width, height, height / 2)
 end
 
---- A rounded rectangle with a triangle at the top
+--- A rounded rect with only some of the corners rounded.
+--
+-- @SHAPE_partially_rounded_rect_EXAMPLE@
+--
 -- @param cr A cairo context
--- @tparam number width The shape with
+-- @tparam number width The shape width
+-- @tparam number height The shape height
+-- @tparam boolean tl If the top left corner is rounded
+-- @tparam boolean tr If the top right corner is rounded
+-- @tparam boolean br If the bottom right corner is rounded
+-- @tparam boolean bl If the bottom left corner is rounded
+-- @tparam number rad The corner radius
+function module.partially_rounded_rect(cr, width, height, tl, tr, br, bl, rad)
+    rad = rad or 10
+    if width / 2 < rad then
+        rad = width / 2
+    end
+
+    if height / 2 < rad then
+        rad = height / 2
+    end
+
+    -- Top left
+    if tl then
+        cr:arc( rad, rad, rad, math.pi, 3*(math.pi/2))
+    else
+        cr:move_to(0,0)
+    end
+
+    -- Top right
+    if tr then
+        cr:arc( width-rad, rad, rad, 3*(math.pi/2), math.pi*2)
+    else
+        cr:line_to(width, 0)
+    end
+
+    -- Bottom right
+    if br then
+        cr:arc( width-rad, height-rad, rad, math.pi*2 , math.pi/2)
+    else
+        cr:line_to(width, height)
+    end
+
+    -- Bottom left
+    if bl then
+        cr:arc( rad, height-rad, rad, math.pi/2, math.pi)
+    else
+        cr:line_to(0, height)
+    end
+
+    cr:close_path()
+end
+
+--- A rounded rectangle with a triangle at the top.
+--
+-- @SHAPE_infobubble_EXAMPLE@
+--
+-- @param cr A cairo context
+-- @tparam number width The shape width
 -- @tparam number height The shape height
 -- @tparam[opt=5] number corner_radius The corner radius
 -- @tparam[opt=10] number arrow_size The width and height of the arrow
 -- @tparam[opt=width/2 - arrow_size/2] number arrow_position The position of the arrow
 function module.infobubble(cr, width, height, corner_radius, arrow_size, arrow_position)
-    corner_radius  = corner_radius  or 5
     arrow_size     = arrow_size     or 10
+    corner_radius  = math.min((height-arrow_size)/2, corner_radius or 5)
     arrow_position = arrow_position or width/2 - arrow_size/2
 
-    cr:move_to(0 ,corner_radius)
+
+    cr:move_to(0 ,corner_radius+arrow_size)
 
     -- Top left corner
     cr:arc(corner_radius, corner_radius+arrow_size, (corner_radius), math.pi, 3*(math.pi/2))
@@ -87,23 +150,39 @@ function module.infobubble(cr, width, height, corner_radius, arrow_size, arrow_p
     cr:close_path()
 end
 
---- A rectangle terminated by an arrow
+--- A rectangle terminated by an arrow.
+--
+-- @SHAPE_rectangular_tag_EXAMPLE@
+--
 -- @param cr A cairo context
--- @tparam number width The shape with
+-- @tparam number width The shape width
 -- @tparam number height The shape height
-function module.rectangular_tag(cr, width, height)
-    cr:move_to(0        , height/2)
-    cr:line_to(height/2 , 0       )
-    cr:line_to(width    , 0       )
-    cr:line_to(width    , height  )
-    cr:line_to(height/2 , height  )
+-- @tparam[opt=height/2] number arrow_length The length of the arrow part
+function module.rectangular_tag(cr, width, height, arrow_length)
+    arrow_length = arrow_length or height/2
+    if arrow_length > 0 then
+        cr:move_to(0            , height/2 )
+        cr:line_to(arrow_length , 0        )
+        cr:line_to(width        , 0        )
+        cr:line_to(width        , height   )
+        cr:line_to(arrow_length , height   )
+    else
+        cr:move_to(0            , 0        )
+        cr:line_to(-arrow_length, height/2 )
+        cr:line_to(0            , height   )
+        cr:line_to(width        , height   )
+        cr:line_to(width        , 0        )
+    end
 
     cr:close_path()
 end
 
---- A simple arrow shape
+--- A simple arrow shape.
+--
+-- @SHAPE_arrow_EXAMPLE@
+--
 -- @param cr A cairo context
--- @tparam number width The shape with
+-- @tparam number width The shape width
 -- @tparam number height The shape height
 -- @tparam[opt=head_width] number head_width The width of the head (/\) of the arrow
 -- @tparam[opt=width /2] number shaft_width The width of the shaft of the arrow
@@ -125,9 +204,12 @@ function module.arrow(cr, width, height, head_width, shaft_width, shaft_length)
     cr:close_path()
 end
 
---- A squeezed hexagon filling the rectangle
+--- A squeezed hexagon filling the rectangle.
+--
+-- @SHAPE_hexagon_EXAMPLE@
+--
 -- @param cr A cairo context
--- @tparam number width The shape with
+-- @tparam number width The shape width
 -- @tparam number height The shape height
 function module.hexagon(cr, width, height)
     cr:move_to(height/2,0)
@@ -140,26 +222,40 @@ function module.hexagon(cr, width, height)
     cr:close_path()
 end
 
---- Double arrow popularized by the vim-powerline module
+--- Double arrow popularized by the vim-powerline module.
+--
+-- @SHAPE_powerline_EXAMPLE@
+--
 -- @param cr A cairo context
--- @tparam number width The shape with
+-- @tparam number width The shape width
 -- @tparam number height The shape height
 -- @tparam[opt=height/2] number arrow_depth The width of the arrow part of the shape
 function module.powerline(cr, width, height, arrow_depth)
     arrow_depth = arrow_depth or height/2
-    cr:move_to(0                   , 0        )
-    cr:line_to(width - arrow_depth , 0        )
-    cr:line_to(width               , height/2 )
-    cr:line_to(width - arrow_depth , height   )
-    cr:line_to(0                   , height   )
-    cr:line_to(arrow_depth         , height/2 )
+    local offset = 0
+
+    -- Avoid going out of the (potential) clip area
+    if arrow_depth < 0 then
+        width  =  width + 2*arrow_depth
+        offset = -arrow_depth
+    end
+
+    cr:move_to(offset                       , 0        )
+    cr:line_to(offset + width - arrow_depth , 0        )
+    cr:line_to(offset + width               , height/2 )
+    cr:line_to(offset + width - arrow_depth , height   )
+    cr:line_to(offset                       , height   )
+    cr:line_to(offset + arrow_depth         , height/2 )
 
     cr:close_path()
 end
 
---- An isosceles triangle
+--- An isosceles triangle.
+--
+-- @SHAPE_isosceles_triangle_EXAMPLE@
+--
 -- @param cr A cairo context
--- @tparam number width The shape with
+-- @tparam number width The shape width
 -- @tparam number height The shape height
 function module.isosceles_triangle(cr, width, height)
     cr:move_to( width/2, 0      )
@@ -168,6 +264,182 @@ function module.isosceles_triangle(cr, width, height)
     cr:close_path()
 end
 
+--- A cross (**+**) symbol.
+--
+-- @SHAPE_cross_EXAMPLE@
+--
+-- @param cr A cairo context
+-- @tparam number width The shape width
+-- @tparam number height The shape height
+-- @tparam[opt=width/3] number thickness The cross section thickness
+function module.cross(cr, width, height, thickness)
+    thickness = thickness or width/3
+    local xpadding   = (width  - thickness) / 2
+    local ypadding   = (height - thickness) / 2
+    cr:move_to(xpadding, 0)
+    cr:line_to(width - xpadding, 0)
+    cr:line_to(width - xpadding, ypadding)
+    cr:line_to(width           , ypadding)
+    cr:line_to(width           , height-ypadding)
+    cr:line_to(width - xpadding, height-ypadding)
+    cr:line_to(width - xpadding, height         )
+    cr:line_to(xpadding        , height         )
+    cr:line_to(xpadding        , height-ypadding)
+    cr:line_to(0               , height-ypadding)
+    cr:line_to(0               , ypadding       )
+    cr:line_to(xpadding        , ypadding       )
+    cr:close_path()
+end
+
+--- A similar shape to the `rounded_rect`, but with sharp corners.
+--
+-- @SHAPE_octogon_EXAMPLE@
+--
+-- @param cr A cairo context
+-- @tparam number width The shape width
+-- @tparam number height The shape height
+-- @tparam number corner_radius 
+function module.octogon(cr, width, height, corner_radius)
+    corner_radius = corner_radius or math.min(10, math.min(width, height)/4)
+    local offset = math.sqrt( (corner_radius*corner_radius) / 2 )
+
+    cr:move_to(offset, 0)
+    cr:line_to(width-offset, 0)
+    cr:line_to(width, offset)
+    cr:line_to(width, height-offset)
+    cr:line_to(width-offset, height)
+    cr:line_to(offset, height)
+    cr:line_to(0, height-offset)
+    cr:line_to(0, offset)
+    cr:close_path()
+end
+
+--- A circle shape.
+--
+-- @SHAPE_circle_EXAMPLE@
+--
+-- @param cr A cairo context
+-- @tparam number width The shape width
+-- @tparam number height The shape height
+function module.circle(cr, width, height)
+    local size = math.min(width, height) / 2
+    cr:arc(width / 2, height / 2, size, 0, 2*math.pi)
+    cr:close_path()
+end
+
+--- A simple rectangle.
+--
+-- @SHAPE_rectangle_EXAMPLE@
+--
+-- @param cr A cairo context
+-- @tparam number width The shape width
+-- @tparam number height The shape height
+function module.rectangle(cr, width, height)
+    cr:rectangle(0, 0, width, height)
+end
+
+--- A diagonal parallelogram with the bottom left corner at x=0 and top right
+-- at x=width.
+--
+-- @SHAPE_parallelogram_EXAMPLE@
+--
+-- @param cr A cairo context
+-- @tparam number width The shape width
+-- @tparam number height The shape height
+-- @tparam[opt=width/3] number base_width The parallelogram base width
+function module.parallelogram(cr, width, height, base_width)
+    base_width = base_width or width/3
+    cr:move_to(width-base_width, 0      )
+    cr:line_to(width           , 0      )
+    cr:line_to(base_width      , height )
+    cr:line_to(0               , height )
+    cr:close_path()
+end
+
+--- A losange.
+--
+-- @SHAPE_losange_EXAMPLE@
+--
+-- @param cr A cairo context
+-- @tparam number width The shape width
+-- @tparam number height The shape height
+function module.losange(cr, width, height)
+    cr:move_to(width/2 , 0        )
+    cr:line_to(width   , height/2 )
+    cr:line_to(width/2 , height   )
+    cr:line_to(0       , height/2 )
+    cr:close_path()
+end
+
+--- A partial rounded bar. How much of the rounded bar is visible depends on
+-- the given percentage value.
+--
+-- Note that this shape is not closed and thus filling it doesn't make much
+-- sense.
+--
+-- @SHAPE_radial_progress_EXAMPLE@
+--
+-- @param cr A cairo context
+-- @tparam number w The shape width
+-- @tparam number h The shape height
+-- @tparam number percent The progressbar percent
+-- @tparam boolean hide_left Do not draw the left side of the shape
+function module.radial_progress(cr, w, h, percent, hide_left)
+    percent = percent or 1
+    local total_length = (2*(w-h))+2*((h/2)*math.pi)
+    local bar_percent  = (w-h)/total_length
+    local arc_percent  = ((h/2)*math.pi)/total_length
+
+    -- Bottom line
+    if percent > bar_percent then
+        cr:move_to(h/2,h)
+        cr:line_to((h/2) + (w-h),h)
+        cr:stroke()
+    elseif percent < bar_percent then
+        cr:move_to(h/2,h)
+        cr:line_to(h/2+(total_length*percent),h)
+        cr:stroke()
+    end
+
+    -- Right arc
+    if percent >= bar_percent+arc_percent then
+        cr:arc(w-h/2 , h/2, h/2,3*(math.pi/2),math.pi/2)
+        cr:stroke()
+    elseif percent > bar_percent and percent < bar_percent+(arc_percent/2) then
+        cr:arc(w-h/2 , h/2, h/2,(math.pi/2)-((math.pi/2)*((percent-bar_percent)/(arc_percent/2))),math.pi/2)
+        cr:stroke()
+    elseif percent >= bar_percent+arc_percent/2 and percent < bar_percent+arc_percent then
+        cr:arc(w-h/2 , h/2, h/2,0,math.pi/2)
+        cr:stroke()
+        local add = (math.pi/2)*((percent-bar_percent-arc_percent/2)/(arc_percent/2))
+        cr:arc(w-h/2 , h/2, h/2,2*math.pi-add,0)
+        cr:stroke()
+    end
+
+    -- Top line
+    if percent > 2*bar_percent+arc_percent then
+        cr:move_to((h/2) + (w-h),0)
+        cr:line_to(h/2,0)
+        cr:stroke()
+    elseif percent > bar_percent+arc_percent and percent < 2*bar_percent+arc_percent then
+        cr:move_to((h/2) + (w-h),0)
+        cr:line_to(((h/2) + (w-h))-total_length*(percent-bar_percent-arc_percent),0)
+        cr:stroke()
+    end
+
+    -- Left arc
+    if not hide_left then
+        if percent > 0.985 then
+            cr:arc(h/2, h/2, h/2,math.pi/2,3*(math.pi/2))
+            cr:stroke()
+        elseif percent  > 2*bar_percent+arc_percent then
+            local relpercent = (percent - 2*bar_percent - arc_percent)/arc_percent
+            cr:arc(h/2, h/2, h/2,3*(math.pi/2)-(math.pi)*relpercent,3*(math.pi/2))
+            cr:stroke()
+        end
+    end
+end
+
 --- Ajust the shape using a transformation object
 --
 -- Apply various transformations to the shape
diff --git a/tests/shape/arrow.lua b/tests/shape/arrow.lua
new file mode 100644
index 000000000..37862fee5
--- /dev/null
+++ b/tests/shape/arrow.lua
@@ -0,0 +1,10 @@
+local shape,cr,show = ... --DOC_HIDE
+
+shape.arrow(cr, 70, 70)
+show(cr) --DOC_HIDE
+ 
+shape.arrow(cr,70,70, 30, 10, 60)
+show(cr) --DOC_HIDE
+ 
+shape.transform(shape.arrow) : rotate_at(35,35,math.pi/2)(cr,70,70)
+show(cr) --DOC_HIDE
diff --git a/tests/shape/circle.lua b/tests/shape/circle.lua
new file mode 100644
index 000000000..35814a009
--- /dev/null
+++ b/tests/shape/circle.lua
@@ -0,0 +1,10 @@
+local shape,cr,show = ... --DOC_HIDE
+
+shape.circle(cr, 70, 70)
+show(cr) --DOC_HIDE
+ 
+shape.circle(cr,20,70)
+show(cr) --DOC_HIDE
+ 
+shape.transform(shape.circle) : scale(0.5, 1)(cr,70,70)
+show(cr) --DOC_HIDE
diff --git a/tests/shape/cross.lua b/tests/shape/cross.lua
new file mode 100644
index 000000000..b98d20d12
--- /dev/null
+++ b/tests/shape/cross.lua
@@ -0,0 +1,10 @@
+local shape,cr,show = ... --DOC_HIDE
+
+shape.cross(cr, 70, 70)
+show(cr) --DOC_HIDE
+ 
+shape.cross(cr,20,70)
+show(cr) --DOC_HIDE
+ 
+shape.transform(shape.cross) : scale(0.5, 1)(cr,70,70)
+show(cr) --DOC_HIDE
diff --git a/tests/shape/hexagon.lua b/tests/shape/hexagon.lua
new file mode 100644
index 000000000..110833411
--- /dev/null
+++ b/tests/shape/hexagon.lua
@@ -0,0 +1,10 @@
+local shape,cr,show = ... --DOC_HIDE
+
+shape.hexagon(cr, 70, 70)
+show(cr) --DOC_HIDE
+ 
+shape.transform(shape.hexagon) : translate(0,15)(cr,70,20)
+show(cr) --DOC_HIDE
+ 
+shape.transform(shape.hexagon) : rotate_at(35,35,math.pi/2)(cr,70,40)
+show(cr) --DOC_HIDE
diff --git a/tests/shape/infobubble.lua b/tests/shape/infobubble.lua
new file mode 100644
index 000000000..9f0710234
--- /dev/null
+++ b/tests/shape/infobubble.lua
@@ -0,0 +1,12 @@
+local shape,cr,show = ... --DOC_HIDE
+
+shape.infobubble(cr, 70, 70)
+show(cr) --DOC_HIDE
+ 
+shape.transform(shape.infobubble) : translate(0, 20)
+   : rotate_at(35,35,math.pi) (cr,70,20,10, 5, 35 - 5)
+show(cr) --DOC_HIDE
+ 
+shape.transform(shape.infobubble)
+   : rotate_at(35,35,3*math.pi/2) (cr,70,70, nil, nil, 40)
+show(cr) --DOC_HIDE
diff --git a/tests/shape/isosceles_triangle.lua b/tests/shape/isosceles_triangle.lua
new file mode 100644
index 000000000..933b52705
--- /dev/null
+++ b/tests/shape/isosceles_triangle.lua
@@ -0,0 +1,10 @@
+local shape,cr,show = ... --DOC_HIDE
+
+shape.isosceles_triangle(cr, 70, 70)
+show(cr) --DOC_HIDE
+ 
+shape.isosceles_triangle(cr,20,70)
+show(cr) --DOC_HIDE
+ 
+shape.transform(shape.isosceles_triangle) : rotate_at(35, 35, math.pi/2)(cr,70,70)
+show(cr) --DOC_HIDE
diff --git a/tests/shape/losange.lua b/tests/shape/losange.lua
new file mode 100644
index 000000000..2205f8bb6
--- /dev/null
+++ b/tests/shape/losange.lua
@@ -0,0 +1,10 @@
+local shape,cr,show = ... --DOC_HIDE
+
+shape.losange(cr, 70, 70)
+show(cr) --DOC_HIDE
+ 
+shape.losange(cr,20,70)
+show(cr) --DOC_HIDE
+ 
+shape.transform(shape.losange) : scale(0.5, 1)(cr,70,70)
+show(cr) --DOC_HIDE
diff --git a/tests/shape/octogon.lua b/tests/shape/octogon.lua
new file mode 100644
index 000000000..1c02da8e2
--- /dev/null
+++ b/tests/shape/octogon.lua
@@ -0,0 +1,10 @@
+local shape,cr,show = ... --DOC_HIDE
+
+shape.octogon(cr, 70, 70)
+show(cr) --DOC_HIDE
+ 
+shape.octogon(cr,70,70,70/2.5)
+show(cr) --DOC_HIDE
+ 
+shape.transform(shape.octogon) : translate(0, 25) (cr,70,20)
+show(cr) --DOC_HIDE
diff --git a/tests/shape/parallelogram.lua b/tests/shape/parallelogram.lua
new file mode 100644
index 000000000..6ae49ca54
--- /dev/null
+++ b/tests/shape/parallelogram.lua
@@ -0,0 +1,10 @@
+local shape,cr,show = ... --DOC_HIDE
+
+shape.parallelogram(cr, 70, 70)
+show(cr) --DOC_HIDE
+ 
+shape.parallelogram(cr,70,20)
+show(cr) --DOC_HIDE
+ 
+shape.transform(shape.parallelogram) : scale(0.5, 1)(cr,70,70)
+show(cr) --DOC_HIDE
diff --git a/tests/shape/partially_rounded_rect.lua b/tests/shape/partially_rounded_rect.lua
new file mode 100644
index 000000000..cb8e87bea
--- /dev/null
+++ b/tests/shape/partially_rounded_rect.lua
@@ -0,0 +1,10 @@
+local shape,cr,show = ... --DOC_HIDE
+
+shape.partially_rounded_rect(cr, 70, 70)
+show(cr) --DOC_HIDE
+ 
+shape.partially_rounded_rect(cr, 70, 70, true)
+show(cr) --DOC_HIDE
+ 
+shape.partially_rounded_rect(cr, 70, 70, true, true, false, true, 30)
+show(cr) --DOC_HIDE
diff --git a/tests/shape/powerline.lua b/tests/shape/powerline.lua
new file mode 100644
index 000000000..37707a60e
--- /dev/null
+++ b/tests/shape/powerline.lua
@@ -0,0 +1,10 @@
+local shape,cr,show = ... --DOC_HIDE
+
+shape.powerline(cr, 70, 70)
+show(cr) --DOC_HIDE
+ 
+shape.transform(shape.powerline) : translate(0, 25) (cr,70,20)
+show(cr) --DOC_HIDE
+ 
+shape.transform(shape.powerline) : translate(0, 25) (cr,70,20, -20)
+show(cr) --DOC_HIDE
diff --git a/tests/shape/radial_progress.lua b/tests/shape/radial_progress.lua
new file mode 100644
index 000000000..ac9350e65
--- /dev/null
+++ b/tests/shape/radial_progress.lua
@@ -0,0 +1,10 @@
+local shape,cr,show = ... --DOC_HIDE
+
+shape.radial_progress(cr, 70, 20, .3)
+show(cr, true) --DOC_HIDE
+ 
+shape.radial_progress(cr, 70, 20, .6)
+show(cr, true) --DOC_HIDE
+ 
+shape.radial_progress(cr, 70, 20, .9)
+show(cr, true) --DOC_HIDE
diff --git a/tests/shape/rectangle.lua b/tests/shape/rectangle.lua
new file mode 100644
index 000000000..79c923968
--- /dev/null
+++ b/tests/shape/rectangle.lua
@@ -0,0 +1,10 @@
+local shape,cr,show = ... --DOC_HIDE
+
+shape.rectangle(cr, 70, 70)
+show(cr) --DOC_HIDE
+ 
+shape.rectangle(cr,20,70)
+show(cr) --DOC_HIDE
+ 
+shape.transform(shape.rectangle) : scale(0.5, 1)(cr,70,70)
+show(cr) --DOC_HIDE
diff --git a/tests/shape/rectangular_tag.lua b/tests/shape/rectangular_tag.lua
new file mode 100644
index 000000000..ccc2684b8
--- /dev/null
+++ b/tests/shape/rectangular_tag.lua
@@ -0,0 +1,13 @@
+local shape,cr,show = ... --DOC_HIDE
+
+shape.rectangular_tag(cr, 70, 70)
+show(cr) --DOC_HIDE
+
+-- shape.rectangular_tag(cr,20,70) --TODO broken --DOC_HIDE
+-- show(cr) --DOC_HIDE
+ 
+shape.transform(shape.rectangular_tag) : translate(0, 30) (cr, 70, 10,  10)
+show(cr) --DOC_HIDE
+ 
+shape.transform(shape.rectangular_tag) : translate(0, 30) (cr, 70, 10, -10)
+show(cr) --DOC_HIDE
diff --git a/tests/shape/rounded_bar.lua b/tests/shape/rounded_bar.lua
new file mode 100644
index 000000000..01894e1c2
--- /dev/null
+++ b/tests/shape/rounded_bar.lua
@@ -0,0 +1,10 @@
+local shape,cr,show = ... --DOC_HIDE
+
+shape.rounded_bar(cr, 70, 70)
+show(cr) --DOC_HIDE
+ 
+shape.rounded_bar(cr, 20, 70)
+show(cr) --DOC_HIDE
+ 
+shape.rounded_bar(cr, 70, 20)
+show(cr) --DOC_HIDE
diff --git a/tests/shape/rounded_rect.lua b/tests/shape/rounded_rect.lua
new file mode 100644
index 000000000..237650a1c
--- /dev/null
+++ b/tests/shape/rounded_rect.lua
@@ -0,0 +1,10 @@
+local shape,cr,show = ... --DOC_HIDE
+
+shape.rounded_rect(cr, 70, 70, 10)
+show(cr) --DOC_HIDE
+ 
+shape.rounded_rect(cr,20,70, 5)
+show(cr) --DOC_HIDE
+ 
+shape.transform(shape.rounded_rect) : translate(0,25) (cr,70,20, 5)
+show(cr) --DOC_HIDE
diff --git a/tests/shape/test-shape.lua b/tests/shape/test-shape.lua
new file mode 100644
index 000000000..6a5484de9
--- /dev/null
+++ b/tests/shape/test-shape.lua
@@ -0,0 +1,31 @@
+-- Test if shape crash when called
+-- Also generate some SVG to be used by the documentation
+-- it also "prove" that the code examples are all working
+local cairo = require( "lgi"         ).cairo
+local shape = require( "gears.shape" )
+local filepath, svgpath = ...
+
+local function get_surface(p)
+    local img = cairo.SvgSurface.create(p, 288, 76)
+    return cairo.Context(img)
+end
+
+local function show(cr, skip_fill)
+    if not skip_fill then
+        cr:set_source_rgba(0.380392156863,0.505882352941,1,0.5)
+        cr:fill_preserve()
+    end
+
+    cr:set_source_rgba(0.380392156863,0.505882352941,1,1)
+    cr:stroke()
+
+    cr:translate(96, 0)
+    cr:reset_clip()
+    cr:rectangle(-3,-3,76,76)
+    cr:clip()
+end
+
+local cr = get_surface(svgpath)
+cr:translate(3,3)
+
+loadfile(filepath)(shape, cr, show)