fix retrieving article description

What made me start this change were two logic bugs: chars_count being
checked against -1 (instead of None) and abstract_delimiter taking
higher priority than unlimited chars_count.

Apart from fixing the above, this commit reorders the if-elif chain
according to priority and, in the documentation, mentions how
abstract_chars_count and abstract_delimiter interact.

Breaking changes, as far as i'm aware:
- abstract_chars_count == -1 is again highest-priority,
- more effort (using abstract_delimiter) before non-compliance,
- chars_count is now an inclusive setting, increasing the article length
  before it has to be shortened by one character.
None of these changes conflicts with the pre-existing documentation and
none should be noticeable in a well-configured environment.

Author: tiosgz

docs/configuration.md

@@ -240,26 +240,23 @@ Output:
 
 ### `abstract_chars_count`: item description length
 
-To fill each [item description element](https://www.w3schools.com/xml/rss_tag_title_link_description_item.asp):
+Used, in combination with `abstract_delimiter`, to determine each [item description element](https://www.w3schools.com/xml/rss_tag_title_link_description_item.asp):
 
 - If this value is set to `-1`, then the articles' full HTML content will be filled into the description element.
-- be careful: if set to `0` and there is no description, the feed's compliance is broken (an item must have a description)
 - Otherwise, the plugin first tries to retrieve the value of the keyword `description` from the [page metadata].
-- If the value is non-negative and no `description` meta is found, then the plugin retrieves the first number of characters of the page content defined by this setting. Retrieved content is the raw markdown converted roughly into HTML.
+- If that fails and `abstract_delimiter` is found in the page, the article content up to (but not including) the delimiter is used.
+- If the above has failed, then the plugin retrieves the first number of characters of the page content defined by this setting. Retrieved content is the raw markdown converted roughly into HTML.
+- Be careful: if set to `0` and there is no description, the feed's compliance is broken (an item must have a description).
 
 `abstract_chars_count`: number of characters to use as item description.
 
 Default: `150`
 
 ----
 
-#### `abstract_delimiter`: abstract delimiter
+### `abstract_delimiter`: abstract delimiter
 
-Used to fill each [item description element](https://www.w3schools.com/xml/rss_tag_title_link_description_item.asp):
-
-- If this value is set to `-1`, then the full HTML content will be filled into the description element.
-- Otherwise, the plugin first tries to retrieve the value of the key `description` from the page metadata.
-- If the value is non-negative and no `description` meta is found, then the plugin retrieves the first number of characters of the page content defined by this setting. Retrieved content is the raw markdown converted rougthly into HTML (i.e. without extension, etc.).
+Please see `abstract_chars_count` for how this setting is used.
 
 `abstract_delimiter`: string to mark .
 

mkdocs_rss_plugin/util.py

@@ -472,18 +472,16 @@ def get_description_or_abstract(
         if chars_count < 0:
             chars_count = None
 
-        # If the abstract chars is not unlimited and the description exists,
-        # return the description.
-        if description and chars_count is not None:
+        # If the full page is wanted (unlimited chars count)
+        if chars_count is None and (in_page.content or in_page.markdown):
+            if in_page.content:
+                return in_page.content
+            else:
+                return markdown.markdown(in_page.markdown, output_format="html5")
+        # If the description is explicitly given
+        elif description:
             return description
-        # If no description and chars_count set to 0, return empty string
-        elif not description and chars_count == 0:
-            logger.warning(
-                f"No description set for page {in_page.file.src_uri} "
-                "and 'abstract_chars_count' set to 0. The feed won't be compliant, "
-                "because an item must have a description."
-            )
-            return ""
+        # If the description is cut by the delimiter
         elif (
             abstract_delimiter
             and (
@@ -495,24 +493,23 @@ def get_description_or_abstract(
                 in_page.markdown[:excerpt_separator_position],
                 output_format="html5",
             )
-        # If chars count is unlimited, use the html content
-        elif in_page.content and chars_count == -1:
-            if chars_count is None or len(in_page.content) < chars_count:
-                return in_page.content[:chars_count]
-        # Use markdown
-        elif in_page.markdown:
-            if chars_count is None or len(in_page.markdown) < chars_count:
-                return markdown.markdown(
-                    in_page.markdown[:chars_count], output_format="html5"
-                )
+        # Use first chars_count from the markdown
+        elif chars_count > 0 and in_page.markdown:
+            if len(in_page.markdown) <= chars_count:
+                return markdown.markdown(in_page.markdown, output_format="html5")
             else:
                 return markdown.markdown(
                     f"{in_page.markdown[: chars_count - 3]}...",
                     output_format="html5",
                 )
-        # Unlimited chars_count but no content is found, then return the description.
+        # No explicit description and no content is found
         else:
-            return description if description else ""
+            logger.warning(
+                f"No description set for page {in_page.file.src_uri} "
+                "and 'abstract_chars_count' set to 0. The feed won't be compliant, "
+                "because an item must have a description."
+            )
+            return ""
 
     def get_image(self, in_page: Page, base_url: str) -> Optional[Tuple[str, str, int]]:
         """Get page's image from page meta or social cards and returns properties.