--- a/setup.py	Wed Nov 20 18:28:10 2019 +0100
+++ b/setup.py	Wed Nov 20 19:40:26 2019 +0100
@@ -72,6 +72,7 @@
           'persistent',
           'pyramid',
           'pyramid_zodbconn',
+          'pyramid_zope_request',
           'pysocks',
           'pytz',
           'transaction',

--- a/src/pyams_utils/registry.py	Wed Nov 20 18:28:10 2019 +0100
+++ b/src/pyams_utils/registry.py	Wed Nov 20 19:40:26 2019 +0100
@@ -21,27 +21,25 @@
 See :ref:`zca` to get a brief introduction about using a local registry with PyAMS packages.
 """
 
-__docformat__ = 'restructuredtext'
+
+import logging
+import threading
+
+import venusian
+from ZODB.POSException import POSError
+from pyramid.events import subscriber
+from pyramid.interfaces import INewRequest
+from pyramid.threadlocal import get_current_registry as get_request_registry, manager
+from zope.component.globalregistry import getGlobalSiteManager
+from zope.component.interfaces import ISite
+from zope.interface import implementedBy, providedBy
+from zope.interface.interfaces import ComponentLookupError
+from zope.traversing.interfaces import IBeforeTraverseEvent
 
 
-# import standard library
-import logging
-logger = logging.getLogger('PyAMS (utils)')
-
-import threading
-import venusian
+__docformat__ = 'restructuredtext'
 
-# import interfaces
-from pyramid.interfaces import INewRequest
-from zope.component.interfaces import ComponentLookupError, ISite
-from zope.traversing.interfaces import IBeforeTraverseEvent
-
-# import packages
-from pyramid.events import subscriber
-from pyramid.threadlocal import manager, get_current_registry as get_request_registry
-from ZODB.POSException import POSError
-from zope.component.globalregistry import getGlobalSiteManager
-from zope.interface import implementedBy, providedBy
+logger = logging.getLogger('PyAMS (utils)')
 
 
 class LocalRegistry(threading.local):

--- a/src/pyams_utils/url.py	Wed Nov 20 18:28:10 2019 +0100
+++ b/src/pyams_utils/url.py	Wed Nov 20 19:40:26 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,