sphinxfeed-lsaffre 0.3.5

Sphinx extension for generating RSS feeds

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

• Support Python 3 (by using feedgen instead of feedformatter).

• Don’t publish items having a publication datetime in the future.

• Ability to write ATOM instead of RSS.

• Detect category and tags fields in the page metadata and if either or both is present, call the 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.

• Additional Sphinx config variables:

  • feed_field_name to change the name of the metadata field to use for specifying the publication date.

  • 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

Installation

You can install it using pip:

pip install sphinxfeed-lsaffre

How to test whether the right version of sphinxfeed is installed:

>>> import sphinxfeed
>>> sphinxfeed.__version__
'0.3.1'

Usage

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

   extensions = [..., 'sphinxfeed']

2. 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"
   feed_use_atom = False
   use_dirhtml = False

3. Optionally use the following metadata fields:

   • date (or any other name configured using feed_field_name)

   • author

   • tags

   • category

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

Maintenance

See also the files LICENSE and CHANGELOG.rst.

Install a developer version:

git clone https://github.com/lsaffre/sphinxfeed.git
pip install -e ".[dev]"

Run the test suite:

$ pytest

Generate an HTML test coverage report:

$ pytest --cov-report=html
$ python -m webbrowser test-reports/index.html

Release a new version to PyPI:

$ hatch version micro
$ git commit -m "release to pypi"
$ git tag v$(hatch version)
$ git push --tags

See Hatch Versioning. and Publishing to PyPI with a Trusted Publisher.

Manually release to PyPI using your machine and token:

$ hatch build
$ twine check --strict dist/*
$ twine upload dist/*

The twine upload step requires authentication credentials in your ~/.pypirc file.