[WIP] Introduce SUMMARY_MAX_PARAGRAPHS

Let the users use only the n-first paragraphs of the article as article
summary.

The advantage of this approach is that we avoid the random word count
ellipsis that will cut content in pieces, while not having to copy the
first paragraph of the article into the article's summary metadata.

If both SUMMARY_MAX_PARAGRAPHS and SUMMARY_MAX_LENGTH are set, then
the SUMMARY_MAX_LENGTH option will apply to the number of paragraphs in
SUMMARY_MAX_PARAGRAPHS.

Author: gagath

RELEASE.md

@@ -0,0 +1,3 @@
+Release type: minor
+
+Allow users to use n-first paragraphs as article summary.

pelican/contents.py

@@ -24,6 +24,7 @@
     sanitised_join,
     set_date_tzinfo,
     slugify,
+    truncate_html_paragraphs,
     truncate_html_words,
 )
 
@@ -431,8 +432,17 @@ def get_summary(self, siteurl):
         if "summary" in self.metadata:
             return self.metadata["summary"]
 
+        content = self.content
+        if (
+            "SUMMARY_MAX_PARAGRAPHS" in self.settings
+            and self.settings["SUMMARY_MAX_PARAGRAPHS"] is not None
+        ):
+            content = truncate_html_paragraphs(
+                self.content, self.settings["SUMMARY_MAX_PARAGRAPHS"]
+            )
+
         if self.settings["SUMMARY_MAX_LENGTH"] is None:
-            return self.content
+            return content
 
         return truncate_html_words(
             self.content,

pelican/tests/test_contents.py

@@ -117,6 +117,31 @@ def test_summary_max_length(self):
         page = Page(**page_kwargs)
         self.assertEqual(page.summary, "")
 
+    def test_summary_paragraph(self):
+        # If a :SUMMARY_MAX_PARAGRAPHS: is set, the generated summary should
+        # not exceed the given paragraph count.
+        page_kwargs = self._copy_page_kwargs()
+        settings = get_settings()
+        page_kwargs["settings"] = settings
+        del page_kwargs["metadata"]["summary"]
+        settings["SUMMARY_MAX_PARAGRAPHS"] = 1
+        settings["SUMMARY_MAX_LENGTH"] = None
+        page = Page(**page_kwargs)
+        self.assertEqual(page.summary, TEST_CONTENT)
+
+    def test_summary_paragraph_max_length(self):
+        # If a :SUMMARY_MAX_PARAGRAPHS: and :SUMMARY_MAX_LENGTH: are set, the
+        # generated summary should not exceed the given paragraph count and
+        # not exceed the given length.
+        page_kwargs = self._copy_page_kwargs()
+        settings = get_settings()
+        page_kwargs["settings"] = settings
+        del page_kwargs["metadata"]["summary"]
+        settings["SUMMARY_MAX_PARAGRAPHS"] = 1
+        settings["SUMMARY_MAX_LENGTH"] = 10
+        page = Page(**page_kwargs)
+        self.assertEqual(page.summary, truncate_html_words(TEST_CONTENT, 10))
+
     def test_summary_end_suffix(self):
         # If a :SUMMARY_END_SUFFIX: is set, and there is no other summary,
         # generated summary should contain the specified marker at the end.

pelican/tests/test_utils.py

@@ -401,6 +401,23 @@ def test_truncate_html_words(self):
         self.assertEqual(utils.truncate_html_words("&#1234 text", 20), "&#1234 text")
         self.assertEqual(utils.truncate_html_words("&#xabc text", 20), "&#xabc text")
 
+    def test_truncate_html_paragraphs(self):
+        one = "<p>one</p>"
+
+        self.assertEqual(utils.truncate_html_paragraphs(one, 0), "")
+        self.assertEqual(utils.truncate_html_paragraphs(one, 1), one)
+        self.assertEqual(utils.truncate_html_paragraphs(one, 2), one)
+
+        two = one + "<p>two</p>"
+        self.assertEqual(utils.truncate_html_paragraphs(two, 1), one)
+        self.assertEqual(utils.truncate_html_paragraphs(two, 2), two)
+
+        three = two + "<p>three</p>"
+        self.assertEqual(utils.truncate_html_paragraphs(three, 1), one)
+        self.assertEqual(utils.truncate_html_paragraphs(three, 2), two)
+        self.assertEqual(utils.truncate_html_paragraphs(three, 3), three)
+        self.assertEqual(utils.truncate_html_paragraphs(three, 4), three)
+
     def test_process_translations(self):
         fr_articles = []
         en_articles = []

pelican/utils.py

@@ -600,6 +600,25 @@ def truncate_html_words(s, num, end_text="…"):
     return out
 
 
+def truncate_html_paragraphs(s, count):
+    """Truncates HTML to a certain number of paragraphs.
+
+    :param count: number of paragraphs to keep
+
+    Newlines in the HTML are preserved.
+    """
+    paragraphs = []
+    tag_stop = 0
+    substr = s[:]
+    for i in range(count):
+        substr = substr[tag_stop:]
+        tag_start = substr.find("<p>")
+        tag_stop = substr.find("</p>") + len("</p>")
+        paragraphs.append(substr[tag_start:tag_stop])
+
+    return "".join(paragraphs)
+
+
 def process_translations(content_list, translation_id=None):
     """Finds translations and returns them.