Improve documentation for #2627/#2630

Signed-off-by: Chris Warrick <kwpolska@gmail.com>
getnikola · Jan 11, 2017 · be0c864 · be0c864
1 parent 20f2263
commit be0c864
Show file tree

Hide file tree

Showing 2 changed files with 18 additions and 10 deletions.
diff --git a/CHANGES.txt b/CHANGES.txt
@@ -1,12 +1,17 @@
+New in master
+=============
+
 Features
 --------
 
-* It is easier to globally modify chronological post sorting.
-  Also, when posts are sorted for taxonomies, the post's title
-  is taken into account before resorting to the post's source path,
-  and the sorting order for title and source path are not reversed
-  anymore. (Issue #2627 / PR #2630)
+* Sort posts chronologically with one unified function (easier to
+  change). (Issue #2627)
+* Sort posts in the following order (most important last): source path
+  (A-Z), title (A-Z), date (reverse chronological order), priority
+  meta number (descending). (Issue #2627)
 
+Bugfixes
+--------
 
 New in v7.8.2
 =============

diff --git a/nikola/nikola.py b/nikola/nikola.py
@@ -1986,15 +1986,18 @@ def create_hierarchy(cat_hierarchy, parent=None):
 
     @staticmethod
     def sort_posts_chronologically(posts, lang=None):
-        """Return sorted list of posts."""
-        # Last tie breaker: sort by source path
+        """Sort a list of posts chronologically.
+
+        This function also takes priority, title and source path into account.
+        """
+        # Last tie breaker: sort by source path (A-Z)
         posts = sorted(posts, key=lambda p: p.source_path)
-        # Next tie breaker: sort by title if language is given
+        # Next tie breaker: sort by title if language is given (A-Z)
         if lang is not None:
             posts = natsort.natsorted(posts, key=lambda p: p.title(lang), alg=natsort.ns.F | natsort.ns.IC)
-        # Next tie breaker: sort by date
+        # Next tie breaker: sort by date (reverse chronological order)
         posts = sorted(posts, key=lambda p: p.date, reverse=True)
-        # Finally, sort by priority
+        # Finally, sort by priority meta value (descending)
         posts = sorted(posts, key=lambda p: int(p.meta('priority')) if p.meta('priority') else 0, reverse=True)
         # Return result
         return posts