new config value 'feed_field_name'

.github/workflows/build.yml

@@ -0,0 +1,48 @@
+name: Test & Publish
+
+on:
+  push:
+    branches: [master]
+    tags: ['v*']
+  pull_request:
+    branches: [master]
+
+jobs:
+  # For all PRs and commits to main, run tests for each supported python version
+  # Note: This is currently expected to fail due to output variations based on
+  # dependency versions
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version: ['3.8', '3.9', '3.10', '3.11', '3.12', '3.13', '3.14']
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+      - name: Install dependencies
+        run: |
+          pip install -U pip setuptools
+          pip install -e .[dev]
+      - name: Run tests
+        run: pytest -vs tests
+
+  # For git tags, build and publish package to PyPI
+  publish:
+    if: ${{ startsWith(github.ref, 'refs/tags/') }}
+    runs-on: ubuntu-latest
+    permissions:
+      id-token: write
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: '3.12'
+      - name: Build package distributions
+        run: |
+          pip install hatch
+          hatch build
+      - name: Publish package distributions to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1

.gitignore

@@ -0,0 +1,12 @@
+# use glob syntax.
+syntax: glob
+
+*.pyc
+*~
+*.egg-info
+.build
+.coverage
+.eggs
+tmp
+.doctrees
+dist

CHANGELOG.rst

@@ -0,0 +1,47 @@
+========================
+The sphinxfeed changelog
+========================
+
+- 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 <https://validator.w3.org/feed/docs/atom.html>`__ instead of RSS.
+
+- 20240601 : look for two new fields ``category`` and ``tags`` in the `page
+  metadata
+  <https://www.sphinx-doc.org/en/master/usage/restructuredtext/field-lists.html>`__
+  and if either field 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.
+
+- 20240718 : merged 7 commits with minor fixes and config updates from `pull
+  request suggested by JWCook <https://github.com/lsaffre/sphinxfeed/pull/1>`__
+
+- 20240720 :  The message "Skipping %s, publish date is in the future" is now
+  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
+  `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.
+
+- 20260325: Add `urn:uuid:` prefix to permalink GUIDs so they validate as a full URL.
+
+- 20260325: Handle trailing slashes in feed_base_url

LICENSE

@@ -0,0 +1,23 @@
+Copyright 2011 Fergus Doyle <fergus.doyle@largeblue.com>
+Copyright 2016-2024 Rumma & Ko Ltd <info@saffre-rumma.net>
+
+Redistribution and use in source and binary forms, with or without modification,
+are permitted provided that the following conditions are met:
+
+1. Redistributions of source code must retain the above copyright notice, this
+   list of conditions and the following disclaimer.
+
+2. Redistributions in binary form must reproduce the above copyright notice,
+   this list of conditions and the following disclaimer in the documentation
+   and/or other materials provided with the distribution.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS “AS IS” AND
+ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
+WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE FOR
+ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
+(INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
+LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON
+ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
+(INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
+SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

README.rst

@@ -1,25 +1,140 @@
-sphinxfeed
-==========
+==========================
+The ``sphinxfeed`` package
+==========================
+.. image:: https://img.shields.io/github/actions/workflow/status/lsaffre/sphinxfeed/build.yml
+  :alt: Build status
+  :target: https://github.com/lsaffre/sphinxfeed/actions
+.. image:: https://img.shields.io/pypi/v/sphinxfeed-lsaffre?color=blue
+  :alt: PyPI - package version
+  :target: https://pypi.org/project/sphinxfeed-lsaffre
+.. image:: https://img.shields.io/pypi/pyversions/sphinxfeed-lsaffre
+  :alt: PyPI - supported python versions
+  :target: https://pypi.org/project/sphinxfeed-lsaffre
 
-This Sphinx extension is derived from Dan Mackinlay's `sphinxcontrib.feed
-<http://bitbucket.org/birkenfeld/sphinx-contrib/src/tip/feed/>`_ package.
+This Sphinx extension is a fork of Fergus Doyle's `sphinxfeed package
+<https://github.com/junkafarian/sphinxfeed>`__ which itself is derived from Dan
+Mackinlay's `sphinxcontrib.feed
+<http://bitbucket.org/birkenfeld/sphinx-contrib/src/tip/feed/>`_ package.  It
+relies on Lars Kiesow's `python-feedgen <https://feedgen.kiesow.be>`__ package
+instead of the defunct `feedformatter
+<https://code.google.com/archive/p/feedformatter/>`_ package or of Django utils to
+generate the feed.
 
-It relies on the `feedformatter <http://code.google.com/p/feedformatter/>`_
-package instead of Django utils to generate the feed.
+Features added
+==============
 
-Usage
------
+- Support Python 3 (by using feedgen instead of feedformatter).
+- Don't publish items having a publication datetime in the future.
+- Ability to write
+  `ATOM <https://validator.w3.org/feed/docs/atom.html>`__ instead of RSS.
+
+- Detect ``category`` and ``tags`` fields in the `page metadata
+  <https://www.sphinx-doc.org/en/master/usage/restructuredtext/field-lists.html>`__
+  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
+    <https://python-feedgen.readthedocs.io/en/latest/api.entry.html#feedgen.entry.FeedEntry.guid>`__
+    for each feed entry. GUIDs are generated based on the entry URL. Or if a
+    ``guid`` value is found in page metadata, that will be used instead. For
+    example, so it can be manually set if the URL changes. Defaults to `False`,
+    in which case the entry URL will be used as a non-permalink ID. Applies to
+    both Atom and RSS feeds.
+
+  - ``feed_use_atom`` to generate an Atom feed instead of RSS
+
+
+Installation
+============
 
-#. Install ``sphinxfeed`` using ``easy_install`` / ``pip`` /
-   ``python setup.py install``
+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
+=====
 
 #. Add ``sphinxfeed`` to the list of extensions in your ``conf.py``::
-   
+
        extensions = [..., 'sphinxfeed']
 
-#. Customise the necessary configuration options to correctly generate the
-   feed::
+#. Customise the necessary configuration options to correctly generate
+   the feed::
 
-       feed_base_url = 'http://YOUR_HOST_URL'
+       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
+
+#. Optionally use the following metadata fields:
+
+   - date (or any other name configured using feed_field_name)
+   - author
+   - guid
+   - tags
+   - category
+
+#. 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 -am "release to pypi"
+  $ git tag v$(hatch version)
+  $ git push --tags
+
+See `Hatch Versioning <https://hatch.pypa.io/1.8/version/>`__. and  `Publishing
+to PyPI with a Trusted Publisher <https://docs.pypi.org/trusted-publishers/>`__.
+
+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.

pyproject.toml

@@ -0,0 +1,80 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "sphinxfeed-lsaffre"
+dynamic = ["version"]
+description = "Sphinx extension for generating RSS feeds"
+readme = "README.rst"
+license = {file = "LICENSE"}
+requires-python = ">= 3.8"
+
+authors = [
+    { name = "Fergus Doyle", email = "fergus.doyle@largeblue.com" },
+    { name = "Luc Saffre", email = "luc@saffre-rumma.net" },
+    { name = "Jordan Cook", email = "jordan.cook.git@proton.me" },
+]
+
+maintainers = [
+    { name = "Luc Saffre", email = "luc@saffre-rumma.net" },
+]
+
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Environment :: Console",
+    "Environment :: Web Environment",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: BSD License",
+    "Operating System :: OS Independent",
+    "Programming Language :: Python",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.8",
+    "Programming Language :: Python :: 3.9",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Topic :: Documentation",
+    "Topic :: Utilities",
+]
+
+dependencies = [
+    "feedgen",
+    "python-dateutil",
+    "Sphinx",
+]
+
+[project.optional-dependencies]
+dev = [
+    "hatch",
+    "pytest",
+    "pytest-cov",
+]
+
+[project.urls]
+homepage = "https://github.com/lsaffre/sphinxfeed"
+issues = "https://github.com/lsaffre/sphinxfeed/issues"
+
+[tool.hatch.version]
+path = "sphinxfeed.py"
+
+[tool.hatch.build.targets.sdist]
+include = ["sphinxfeed.py"]
+
+[tool.hatch.build.targets.wheel]
+only-include = ["sphinxfeed.py"]
+
+[tool.hatch.build]
+dev-mode-dirs = ["."]
+
+# Coverage report config: by default, show condensed terminal output
+[tool.coverage.run]
+branch = true
+source = ['.']
+omit = ['tests/*', 'tasks.py']
+
+[tool.coverage.html]
+directory = 'test-reports'
+
+[tool.pytest.ini_options]
+addopts = "--cov --cov-report=term"