Merge pull request #1236 from sixtyfathoms/fix/issue-1184

Update wording on dictionary default ordering

2 files changed, 13 insertions, 6 deletions

diff --git a/docs/templates.rst b/docs/templates.rst
index 4f0c9db..3afa71f 100644
--- a/docs/templates.rst
+++ b/docs/templates.rst
@@ -688,9 +688,17 @@ iterate over containers like `dict`::
     {% endfor %}
     </dl>
 
-Note, however, that **Python dicts are not ordered**; so you might want to
-either pass a sorted ``list`` of ``tuple`` s -- or a
-``collections.OrderedDict`` -- to the template, or use the `dictsort` filter.
+Python dicts may not be in the order you want to display them in. If
+order matters, use the ``|dictsort`` filter.
+
+.. code-block:: jinja
+
+    <dl>
+    {% for key, value in my_dict | dictsort %}
+        <dt>{{ key|e }}</dt>
+        <dd>{{ value|e }}</dd>
+    {% endfor %}
+    </dl>
 
 Inside of a for-loop block, you can access some special variables:
 
diff --git a/src/jinja2/filters.py b/src/jinja2/filters.py
index 5ff0bdd..af9a452 100644
--- a/src/jinja2/filters.py
+++ b/src/jinja2/filters.py
@@ -307,9 +307,8 @@ def do_dictsort(
     by: 'te.Literal["key", "value"]' = "key",
     reverse: bool = False,
 ) -> "t.List[t.Tuple[K, V]]":
-    """Sort a dict and yield (key, value) pairs. Because python dicts are
-    unsorted you may want to use this function to order them by either
-    key or value:
+    """Sort a dict and yield (key, value) pairs. Python dicts may not
+    be in the order you want to display them in, so sort them first.
 
     .. sourcecode:: jinja