--- a/src/pyams_utils/url.py	Wed Nov 20 19:14:09 2019 +0100
+++ b/src/pyams_utils/url.py	Wed Nov 20 19:14:30 2019 +0100
@@ -28,7 +28,30 @@
     """Generate an SEO-friendly content URL from it's title
 
     The original title is translated to remove accents, converted to lowercase, and words
-    shorter than three characters are removed; terms are joined by hyphens.
+    shorter than three characters (by default) are removed; terms are joined by hyphens.
+
+    :param title: the input text
+    :param min_word_length: minimum length of words to keep
+
+    >>> from pyams_utils.url import generate_url
+    >>> generate_url('This is my test')
+    'this-is-my-test'
+
+    Single letters are removed from generated URLs:
+    >>> generate_url('This word has a single a')
+    'this-word-has-single'
+
+    But you can define the minimum length of word:
+    >>> generate_url('This word has a single a', min_word_length=4)
+    'this-word-single'
+
+    If input text contains slashes, they are replaced with hyphens:
+    >>> generate_url('This string contains/slash')
+    'this-string-contains-slash'
+
+    Punctation and special characters are completely removed:
+    >>> generate_url('This is a string with a point. And why not?')
+    'this-is-string-with-point-and-why-not'
     """
     return '-'.join(filter(lambda x: len(x) >= min_word_length,
                            translate_string(title.replace('/', '-'), escape_slashes=False,