lsaffre / sphinxfeed

Automatically generates an RSS feed when a build is run

The sphinxfeed package

This repository is published on https://github.com/lsaffre/sphinxfeed

This Sphinx extension is a fork of Fergus Doyle's sphinxfeed package which itself is derived from Dan Mackinlay's sphinxcontrib.feed package. It relies on Lars Kiesow's python-feedgen package instead of the defunct feedformatter package or of Django utils to generate the feed.

Features added by Luc Saffre:

• 20190315 : Support Python 3 (by using feedgen instead of feedformatter). feed_description is no longer optional.
• new config variable feed_field_name to change the name of the metadata field to use for specifying the publication date.
• don't publish items whose publication datetime is in the future.
• respect use_dirhtml option from rstgen when calculating the url
• 20240530 : add support to write ATOM instead of RSS.
• 20240601 : look for two new fields category and tags in the page metadata and if either field or both is present, call the :meth:`feedgen.FeedEntry.category` method to add <category> elements to the feed item. The difference between category and tags is that the category of a blog post may contain whitespace while the tags metadata field is a space-separated list of tags, so each tag must be a single word. Both the category and each tag will become a <category> element in the feed item.

Usage

1. Install sphinxfeed using something like the following:

   git clone https://github.com/lsaffre/sphinxfeed.git
   pip install -e sphinxfeed
   

2. Add sphinxfeed to the list of extensions in your conf.py:

   extensions = [..., 'sphinxfeed']
   

3. Customise the necessary configuration options to correctly generate the feed:

   feed_base_url = 'https://YOUR_HOST_URL'
   feed_author = 'YOUR NAME'
   feed_description = "A longer description"
   
   # optional options
   feed_field_name = 'date'  # default value is "Publish Date"
   

4. Sphinxfeed will include only .rst file that have a :date: field with a data that does not lie in the future.