Merge remote-tracking branch 'upstream/main' into hacky-fix-relative-…

…links-in-feed
Guts · May 5, 2024 · a344855 · a344855
2 parents 8c5db54 + 857ca1a
commit a344855
Show file tree

Hide file tree

Showing 15 changed files with 259 additions and 61 deletions.
diff --git a/.github/labeler.yml b/.github/labeler.yml
@@ -1,8 +1,59 @@
+bug:
+  - head-branch:
+      - ^fix
+      - fix
+      - ^hotfix
+      - hotfix
+
 ci-cd:
-  - .github/**/*
+  - changed-files:
+      - any-glob-to-any-file:
+          - .github/**
 
 dependencies:
-  - any: ['requirements.txt', 'requirements/*.txt']
+  - changed-files:
+      - any-glob-to-any-file:
+          - requirements/*.txt
+          - requirements.txt
 
 documentation:
-  - docs/**/*
+  - changed-files:
+      - any-glob-to-any-file:
+          - "*.md"
+          - docs/**
+          - requirements/documentation.txt
+  - head-branch:
+      - ^docs
+      - documentation
+
+enhancement:
+  - head-branch:
+      - ^feature
+      - feature
+      - ^improve
+      - improve
+
+packaging:
+  - changed-files:
+      - any-glob-to-any-file:
+          - MANIFEST.in
+          - setup.py
+  - head-branch:
+      - ^packaging
+      - packaging
+
+quality:
+  - changed-files:
+      - any-glob-to-any-file:
+          - tests/**/*
+
+tooling:
+  - changed-files:
+      - any-glob-to-any-file:
+          - ".*"
+          - codecov.yml
+          - setup.cfg
+          - .vscode/**/*
+  - head-branch:
+      - ^tooling
+      - tooling
diff --git a/.github/workflows/lint-and-tests.yml b/.github/workflows/lint-and-tests.yml
@@ -5,23 +5,28 @@ name: "🐍 Lint and Test"
 # events but only for the master branch
 on:
   pull_request:
-    branches: [main]
+    branches:
+      - main
     paths-ignore:
       - "docs/**"
   push:
-    branches: [main]
+    branches:
+      - main
     paths-ignore:
       - "docs/**"
 
-# A workflow run is made up of one or more jobs that can run sequentially or in parallel
 jobs:
-  # This workflow contains a single job called "build"
   lintest:
     runs-on: ubuntu-latest
     strategy:
       fail-fast: false
       matrix:
-        python-version: ["3.8", "3.9", "3.10", "3.11", "3.12"]
+        python-version:
+          - "3.8"
+          - "3.9"
+          - "3.10"
+          - "3.11"
+          - "3.12"
 
     # Steps represent a sequence of tasks that will be executed as part of the job
     steps:
@@ -56,4 +61,11 @@ jobs:
         run: python -m pytest
 
       - name: Upload coverage to Codecov
-        uses: codecov/[email protected]
+        uses: codecov/[email protected]
+        with:
+          env_vars: PYTHON
+          flags: unittests
+          name: Code Coverage for unittests on python-${{ matrix.python-version }}]
+        env:
+          PYTHON: ${{ matrix.python-version }}
+          CODECOV_TOKEN: ${{ secrets.CODECOV_TOKEN }}
diff --git a/.github/workflows/pr-auto-labeler.yml b/.github/workflows/pr-auto-labeler.yml
@@ -6,7 +6,7 @@ jobs:
   triage:
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/labeler@v4
+      - uses: actions/labeler@v5
         with:
           repo-token: "${{ secrets.GITHUB_TOKEN }}"
           sync-labels: true
diff --git a/.github/workflows/release.yml b/.github/workflows/release.yml
@@ -54,7 +54,6 @@ jobs:
         if: startsWith(github.ref, 'refs/tags')
         uses: pypa/gh-action-pypi-publish@release/v1
         with:
-          password: ${{ secrets.PYPI_API_TOKEN }}
           print-hash: true
 
       - name: Create/update release on GitHub

diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -17,6 +17,20 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 -->
 
+## 1.12.2 - 2024-04-30
+
+### Bugs fixes 🐛
+
+* Fix: abstract limit by @tiosgz and @Guts in <https://github.com/Guts/mkdocs-rss-plugin/pull/268>
+
+### Tooling 🔧
+
+* ci: fix missing Codecov token by @Guts in <https://github.com/Guts/mkdocs-rss-plugin/pull/269>
+
+### Documentation 📖
+
+* Update docs on locale configuration by @YDX-2147483647 in <https://github.com/Guts/mkdocs-rss-plugin/pull/256>
+
 ## 1.12.1 - 2024-02-14
 
 ### Bugs fixes 🐛

diff --git a/docs/configuration.md b/docs/configuration.md
@@ -240,28 +240,26 @@ 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
-
-Used to fill each [item description element](https://www.w3schools.com/xml/rss_tag_title_link_description_item.asp):
+### `abstract_delimiter`: abstract delimiter
 
-- 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. A value of `""` (the empty string) disables this step.
 
-`abstract_delimiter`: string to mark .
+`abstract_delimiter`: string to mark where the description ends.
 
 Default: `<!-- more -->`
 

diff --git a/docs/integrations.md b/docs/integrations.md
@@ -47,20 +47,60 @@ You need to customize the theme's template. Typically, in `main.html`:
 
 To facilitate the discovery of JSON feeds, it's [recommended](https://www.jsonfeed.org/version/1.1/#discovery-a-name-discovery-a) to add relevant meta-tags in `<head>` section in HTML pages.
 
-<!-- ### Automatically set with Material theme
+### Manually { #feed-discovery-manual-json }
 
-If you're using the Material theme, everything is automagically set up (see [the related documentation page](https://squidfunk.github.io/mkdocs-material/setup/setting-up-a-blog/#rss)) :partying_face:. -->
+You need to customize the theme's template. Firstly, you need to declare the folder where you store your template overrides:
 
-### Manually { #feed-discovery-manual-json }
+```yaml title="mkdocs.yml"
+[...]
+theme:
+  name: material
+  custom_dir: docs/theme/overrides
+[...]
+```
 
-You need to customize the theme's template. Typically, in `main.html`:
+Then add a `main.html` inside:
 
-```html
+```jinja title="docs/theme/overrides/main.html"
 {% extends "base.html" %}
 
 {% block extrahead %}
-  <!-- JSON Feed -->
-  <link rel="alternate" title="JSON feed of created content" type="application/feed+json" href="{{ config.site_url }}feed_rss_created.xml" />
-  <link rel="alternate" title="JSON feed of updated content" type="application/feed+json" href="{{ config.site_url }}feed_rss_updated.xml" />
+{# JSON Feed #}
+{% if "rss" in config.plugins %}
+<link
+  rel="alternate"
+  type="application/feed+json"
+  title="JSON feed" href="{{ 'feed_json_created.json' | url }}"
+  />
+<link
+  rel="alternate"
+  type="application/feed+json"
+  title="JSON feed of updated content"
+  href="{{ 'feed_json_updated.json' | url }}" />
+{% endif %}
 {% endblock %}
 ```
+
+If your `main.html` is getting too large, or if you like to modularize anything with more than 3 lines, you can also put this configuration in a separated `partials` file:
+
+```jinja title="content/theme/partials/json_feed.html.jinja2"
+{# JSON Feed #}
+{% if "rss" in config.plugins %}
+<link
+  rel="alternate"
+  type="application/feed+json"
+  title="JSON feed" href="{{ 'feed_json_created.json' | url }}"
+  />
+<link
+  rel="alternate"
+  type="application/feed+json"
+  title="JSON feed of updated content"
+  href="{{ 'feed_json_updated.json' | url }}" />
+{% endif %}
+```
+
+And include it in `main.html`:
+
+```jinja title="docs/theme/overrides/main.html"
+{% include "partials/json_feed.html.jinja2" %}
+```
diff --git a/docs/theme/overrides/main.html b/docs/theme/overrides/main.html
@@ -0,0 +1,16 @@
+{% extends "base.html" %}
+
+{% block extrahead %}
+{% if "rss" in config.plugins %}
+<link
+  rel="alternate"
+  type="application/feed+json"
+  title="JSON feed" href="{{ 'feed_json_created.json' | url }}"
+  />
+<link
+  rel="alternate"
+  type="application/feed+json"
+  title="JSON feed of updated content"
+  href="{{ 'feed_json_updated.json' | url }}" />
+{% endif %}
+{% endblock %}
diff --git a/mkdocs.yml b/mkdocs.yml
@@ -134,6 +134,7 @@ plugins:
 
 theme:
   name: material
+  custom_dir: docs/theme/overrides
   favicon: assets/logo_rss_plugin_mkdocs.svg
   features:
     - content.action.edit

diff --git a/mkdocs_rss_plugin/__about__.py b/mkdocs_rss_plugin/__about__.py
@@ -40,7 +40,7 @@
 __title_clean__ = "".join(e for e in __title__ if e.isalnum())
 __uri__ = "https://github.com/Guts/mkdocs-rss-plugin/"
 
-__version__ = "1.12.1"
+__version__ = "1.12.2"
 __version_info__ = tuple(
     [
         int(num) if num.isdigit() else num

diff --git a/mkdocs_rss_plugin/util.py b/mkdocs_rss_plugin/util.py
@@ -490,47 +490,40 @@ def get_description_or_abstract(
 
         description = in_page.meta.get("description")
 
-        # Set chars_count to None if it is set to be unlimited, for slicing.
-        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 == -1 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 abstract is cut by the delimiter
         elif (
             abstract_delimiter
             and (excerpt_separator_position := html.find(abstract_delimiter)) > -1
         ):
             return relative_links_resolve_to_page(
                 html[:excerpt_separator_position], in_page.canonical_url
             )
-        # 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 (or empty) abstract found
         else:
-            return description if description else ""
+            logger.warning(
+                f"No description generated from metadata or content of the page {in_page.file.src_uri}, "
+                "therefore 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.

diff --git a/requirements/documentation.txt b/requirements/documentation.txt
@@ -1,7 +1,7 @@
 # Documentation
 # -----------------------
 
-mkdocs-git-committers-plugin-2>=1.2,<2.3
+mkdocs-git-committers-plugin-2>=1.2,<2.4
 mkdocs-git-revision-date-localized-plugin>=1,<1.3
 mkdocs-material[imaging]>=9.5.1,<10
 mkdocs-minify-plugin==0.8.*

diff --git a/tests/fixtures/docs/page_without_meta_early_delimiter.md b/tests/fixtures/docs/page_without_meta_early_delimiter.md
@@ -0,0 +1,5 @@
+# Page without meta with early delimiter
+
+<!-- more -->
+
+Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat. Duis aute irure dolor in reprehenderit in voluptate velit esse cillum dolore eu fugiat nulla pariatur. Excepteur sint occaecat cupidatat non proident, sunt in culpa qui officia deserunt mollit anim id est laborum.
diff --git a/tests/fixtures/mkdocs_item_delimiter_empty.yml b/tests/fixtures/mkdocs_item_delimiter_empty.yml
@@ -0,0 +1,23 @@
+# Project information
+site_name: MkDocs RSS Plugin - TEST
+site_description: Basic setup to test against MkDocs RSS plugin
+site_author: Julien Moura (Guts)
+site_url: https://guts.github.io/mkdocs-rss-plugin
+copyright: "Guts - In Geo Veritas"
+
+# Repository
+repo_name: "guts/mkdocs-rss-plugin"
+repo_url: "https://github.com/guts/mkdocs-rss-plugin"
+
+use_directory_urls: true
+
+plugins:
+  - rss:
+      abstract_delimiter: ""
+
+theme:
+  name: readthedocs
+
+# Extensions to enhance markdown
+markdown_extensions:
+  - meta