tutorial RSS feeds

_ext/rss.py

@@ -0,0 +1,101 @@
+"""
+Create an RSS feed of tutorials
+
+Cribbed from: https://github.com/python/peps/blob/main/pep_sphinx_extensions/generate_rss.py
+"""
+
+from dataclasses import dataclass, asdict
+from datetime import datetime, UTC
+from email.utils import format_datetime
+from html import escape
+from pprint import pformat
+from typing import TYPE_CHECKING
+from urllib.parse import urljoin
+
+if TYPE_CHECKING:
+    from sphinx.application import Sphinx
+
+
+def _format_rfc_2822(dt: datetime) -> str:
+    datetime = dt.replace(tzinfo=UTC)
+    return format_datetime(datetime, usegmt=True)
+
+
+@dataclass
+class RSSItem:
+    title: str
+    date: datetime
+    description: str
+    url: str
+    author: str = "PyOpenSci"
+
+    @classmethod
+    def from_meta(cls, page_name: str, meta: dict, app: "Sphinx") -> "RSSItem":
+        """Create from a page's metadata"""
+        url = urljoin(app.config.html_baseurl, app.builder.get_target_uri(page_name))
+        # purposely don't use `get` here because we want to error if these fields are absent
+        return RSSItem(
+            title=meta[":og:title"],
+            description=meta[":og:description"],
+            date=datetime.fromisoformat(meta["date"]),
+            author=meta.get(":og:author", "PyOpenSci"),
+            url=url,
+        )
+
+    def render(self) -> str:
+        return f"""\
+<item>
+  <title>{escape(self.title, quote=False)}</title>
+  <link>{escape(self.url, quote=False)}</link>
+  <description>{escape(self.description, quote=False)}</description>
+  <author>{escape(self.author, quote=False)}</author>
+  <guid isPermaLink="true">{self.url}</guid>
+  <pubDate>{_format_rfc_2822(self.date)}</pubDate>
+</item>"""
+
+
+@dataclass
+class RSSFeed:
+    items: list[RSSItem]
+    last_build_date: datetime = datetime.now()
+    title: str = "PyOpenSci Tutorials"
+    link: str = "https://www.pyopensci.org/python-package-guide/tutorials/intro.html"
+    self_link: str = "https://www.pyopensci.org/python-package-guide/tutorials.rss"
+    description: str = "Tutorials for learning python i guess!!!"
+    language: str = "en"
+
+    def render(self) -> str:
+        items = sorted(self.items, key=lambda i: i.date, reverse=True)
+        items = "\n".join([item.render() for item in items])
+        return f"""\
+<?xml version='1.0' encoding='UTF-8'?>
+<rss xmlns:atom="http://www.w3.org/2005/Atom" xmlns:content="http://purl.org/rss/1.0/modules/content/" version="2.0">
+  <channel>
+    <title>{self.title}</title>
+    <link>{self.link}</link>
+    <atom:link href="{self.self_link}" rel="self"/>
+    <description>{self.description}</description>
+    <language>{self.language}</language>
+    <lastBuildDate>{_format_rfc_2822(self.last_build_date)}</lastBuildDate>
+{items}
+  </channel>
+</rss>
+        """
+
+
+def generate_tutorials_feed(app: "Sphinx"):
+    from sphinx.util import logging
+
+    logger = logging.getLogger("_ext.rss")
+    logger.info("Generating RSS feed for tutorials")
+    metadata = app.builder.env.metadata
+    tutorials = [t for t in metadata if t.startswith("tutorials/")]
+    feed_items = [RSSItem.from_meta(t, metadata[t], app) for t in tutorials]
+    feed = RSSFeed(items=feed_items)
+    with open(app.outdir / "tutorials.rss", "w") as f:
+        f.write(feed.render())
+
+    logger.info(
+        f"Generated RSS feed for tutorials, wrote to {app.outdir / 'tutorials.rss'}"
+    )
+    logger.debug(f"feed items: \n{pformat([asdict(item) for item in feed_items])}")

conf.py

@@ -10,12 +10,17 @@
 # add these directories to sys.path here. If the directory is relative to the
 # documentation root, use os.path.abspath to make it absolute, like shown here.
 #
-# import os
-# import sys
-# sys.path.insert(0, os.path.abspath('.'))
+import os
+import sys
+sys.path.insert(0, os.path.abspath('.'))
 from datetime import datetime
 import subprocess
 import os
+from typing import TYPE_CHECKING
+from _ext import rss
+
+if TYPE_CHECKING:
+    from sphinx.application import Sphinx
 
 current_year = datetime.now().year
 organization_name = "pyOpenSci"
@@ -199,3 +204,14 @@
 bibtex_bibfiles = ["bibliography.bib"]
 # myst complains about bibtex footnotes because of render order
 suppress_warnings = ["myst.footnote"]
+
+
+def _post_build(app: "Sphinx", exception: Exception | None) -> None:
+    rss.generate_tutorials_feed(app)
+
+
+def setup(app: "Sphinx"):
+    app.connect("build-finished", _post_build)
+
+    # Parallel safety: https://www.sphinx-doc.org/en/master/extdev/index.html#extension-metadata
+    return {"parallel_read_safe": True, "parallel_write_safe": True}

tutorials/add-license-coc.md

@@ -1,3 +1,9 @@
+---
+:og:description: Placeholder text!!!!
+:og:title: Add a License and Code of Conduct to your python package
+date: 1970-01-02
+---
+
 # Add a `LICENSE` & `CODE_OF_CONDUCT` to your Python package
 
 In the [previous lesson](add-readme) you:

tutorials/add-readme.md

@@ -1,3 +1,9 @@
+---
+:og:description: Placeholder text!!!!
+:og:title: Add a README file to your Python package
+date: 1970-01-03
+---
+
 # Add a README file to your Python package
 
 In the previous lessons you learned:

tutorials/command-line-reference.md

@@ -1,3 +1,9 @@
+---
+:og:description: Placeholder text!!!!
+:og:title: Command Line Reference Guide
+date: 1970-01-04
+---
+
 # Command Line Reference Guide
 
 ```{important}

tutorials/get-to-know-hatch.md

@@ -1,3 +1,9 @@
+---
+:og:description: Placeholder text!!!!
+:og:title: Get to Know Hatch
+date: 1970-01-05
+---
+
 # Get to Know Hatch
 
 Our Python packaging tutorials use the tool

tutorials/installable-code.md

@@ -1,6 +1,7 @@
 ---
 :og:description: Learn how to make your Python code installable so you can use it across projects.
 :og:title: Make your Python code installable so it can be used across projects
+date: 1970-01-01
 ---
 
 # Make your Python code installable

tutorials/intro.md

@@ -1,3 +1,9 @@
+---
+:og:description: Placeholder text!!!!
+:og:title: Python packaging 101
+date: 1970-01-05
+---
+
 (packaging-101)=
 # Python packaging 101
 

tutorials/publish-conda-forge.md

@@ -1,3 +1,9 @@
+---
+:og:description: Placeholder text!!!!
+:og:title: Publish your Python package that is on PyPI to conda-forge
+date: 1970-01-06
+---
+
 # Publish your Python package that is on PyPI to conda-forge
 
 In the previous lessons, you've learned:

tutorials/publish-pypi.md

@@ -1,3 +1,9 @@
+---
+:og:description: Placeholder text!!!!
+:og:title: Publish your Python package to PyPI
+date: 1970-01-07
+---
+
 # Publish your Python package to PyPI
 
 :::{todo}

tutorials/pyproject-toml.md

@@ -1,3 +1,9 @@
+---
+:og:description: Placeholder text!!!!
+:og:title: Make your Python package PyPI ready - pyproject.toml
+date: 1970-01-08
+---
+
 # Make your Python package PyPI ready - pyproject.toml
 
 In [the installable code lesson](installable-code), you learned how to add the bare minimum information to a `pyproject.toml` file to make it installable. You then learned how to [publish a bare minimum version of your package to PyPI](publish-pypi.md).

tutorials/setup-py-to-pyproject-toml.md

@@ -1,3 +1,9 @@
+---
+:og:description: Placeholder text!!!!
+:og:title: Using Hatch to Migrate setup.py to a pyproject.toml
+date: 1970-01-09
+---
+
 # Using Hatch to Migrate setup.py to a pyproject.toml
 
 Hatch can be particularly useful to generate your project's `pyproject.toml` if your project already has a `setup.py`.