Merge pull request #10 from JWCook/permalink

 Add `feed_entry_permalink` option to toggle setting `FeedEntry.guid`

CHANGELOG.rst

@@ -30,8 +30,14 @@ The sphinxfeed changelog
   logged at level INFO instead of WARNING because we don't want the
   ``sphinx-build -W`` to fail in this situation.
 
-- 20240720 : Removed dependency from ``atelier`` because it's easier to call 
+- 20240720 : Removed dependency from ``atelier`` because it's easier to call
   `subprocess.check_output()` directly here.
 
 - 20240722 : Support additional timestamp formats (any format supported by
   `dateutil <https://dateutil.readthedocs.io/en/stable/examples.html#parse-examples>`__)
+
+- 20240728: Add ``feed_entry_permalink`` option to set a permalink GUID for each
+  feed entry. If a `guid` value is found in the metadata, that will be used;
+  otherwise, a new one will be generated based on the entry URL.
+  Defaults to ``False``, in which case the entry URL will be used as a
+  non-permalink ID.  Applies to both Atom and RSS feeds.

README.rst

@@ -45,6 +45,8 @@ Features added
   - ``use_dirhtml`` to specify whether `dirhtml` instead of `html` builder is
     used when calculating the url
 
+  - ``feed_entry_permalink`` to set a permalink GUID for each feed entry
+
   - ``feed_use_atom`` to generate an Atom feed instead of RSS
 
 

sphinxfeed.py

@@ -8,12 +8,13 @@
 
 import os.path
 from datetime import datetime
-from dateutil.tz import tzlocal
+from uuid import NAMESPACE_URL, uuid5
+
 from dateutil.parser import parse as parse_date
+from dateutil.tz import tzlocal
+from feedgen.feed import FeedEntry, FeedGenerator
 from sphinx.util.logging import getLogger
 
-from feedgen.feed import FeedGenerator
-from feedgen.feed import FeedEntry
 
 doc_trees = []  # for atelier
 logger = getLogger(__name__)
@@ -30,6 +31,7 @@ def setup(app):
     app.add_config_value('feed_author', '', 'html')
     app.add_config_value('feed_field_name', 'Publish Date', 'env')
     app.add_config_value('feed_filename', 'rss.xml', 'html')
+    app.add_config_value('feed_entry_permalink', False, 'html')
     app.add_config_value('feed_use_atom', False, 'html')
     app.add_config_value('use_dirhtml', False, 'html')
 
@@ -87,11 +89,18 @@ def create_feed_item(app, pagename, templatename, ctx, doctree):
     if not app.config.use_dirhtml:
         href += ctx['file_suffix']
     item.link(href=href)
-    if app.config.feed_use_atom:
-        item.id(href)
     item.description(ctx.get('body'))
     item.published(pubdate)
 
+    # Entry ID option 1: Use a GUID as a permalink. Also sets item.id for Atom.
+    if app.config.feed_entry_permalink:
+        if not (guid :=  metadata.get('guid')):
+            guid = uuid5(NAMESPACE_URL, href)
+        item.guid(str(guid), permalink=True)
+    # Entry ID option 2: Use the URL as the ID. Also sets item.guid (non-permalink) for RSS.
+    else:
+        item.id(href)
+
     if author := metadata.get('author'):
         # author may be a str (in field list/frontmatter) or a dict (expected by feedgen)
         if isinstance (author, str):

tests/outputs/rss.xml

@@ -13,6 +13,7 @@
         <item>
             <title>Second day</title>
             <link>http://news.example.com/second.html</link>
+            <guid>65a78116-5715-4f78-bbd4-384a018c99f9</guid>
             <description>
             &lt;section id="second-day"&gt;
             &lt;h1&gt;Second day&lt;a class="headerlink" href="#second-day" title="Link to this heading"&gt;¶&lt;/a&gt;&lt;/h1&gt;
@@ -28,6 +29,7 @@
         <item>
             <title>First day</title>
             <link>http://news.example.com/first.html</link>
+            <guid>f21329fa-c178-5550-9bbd-8cd2f591844a</guid>
             <description>
             &lt;section id="first-day"&gt;
             &lt;h1&gt;First day&lt;a class="headerlink" href="#first-day" title="Link to this heading"&gt;¶&lt;/a&gt;&lt;/h1&gt;

tests/sources/test-rss/conf.py

@@ -16,4 +16,5 @@
 feed_field_name = 'date'
 feed_description = "Joe's blog"
 feed_filename = 'rss.xml'
+feed_entry_permalink = True
 feed_use_atom = False

tests/sources/test-rss/second.rst

@@ -1,6 +1,7 @@
 :date: March 12 2018, 11:30 PM UTC
 :author: Joe
 :tags: poetry, unit-test
+:guid: 65a78116-5715-4f78-bbd4-384a018c99f9
 
 ==========
 Second day

tests/test_sphinxfeed.py

@@ -16,7 +16,6 @@
 
 from tests.conftest import OUTPUT_DIR
 
-RSS_ITEM_ATTRIBUTES = ["title", "link", "description", "pubDate"]
 RSS_META_ATTRIBUTES = [
     "copyright",
     "description",
@@ -26,6 +25,13 @@
     "link",
     "title",
 ]
+RSS_ITEM_ATTRIBUTES = [
+    "guid",
+    "title",
+    "link",
+    "description",
+    "pubDate",
+]
 
 ATOM_SCHEMA = "http://www.w3.org/2005/Atom"
 ATOM_META_ATTRIBUTES = [