Metadata-Version: 2.4
Name: sphinxfeed-lsaffre
Version: 0.3.5
Summary: Sphinx extension for generating RSS feeds
Project-URL: homepage, https://github.com/lsaffre/sphinxfeed
Project-URL: issues, https://github.com/lsaffre/sphinxfeed/issues
Author-email: Fergus Doyle <fergus.doyle@largeblue.com>, Luc Saffre <luc@saffre-rumma.net>, Jordan Cook <jordan.cook.git@proton.me>
Maintainer-email: Luc Saffre <luc@saffre-rumma.net>
License: 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.
License-File: LICENSE
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console
Classifier: Environment :: Web Environment
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: BSD License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Documentation
Classifier: Topic :: Utilities
Requires-Python: >=3.8
Requires-Dist: feedgen
Requires-Dist: python-dateutil
Requires-Dist: sphinx
Provides-Extra: dev
Requires-Dist: hatch; extra == 'dev'
Requires-Dist: pytest; extra == 'dev'
Requires-Dist: pytest-cov; extra == 'dev'
Description-Content-Type: text/x-rst

==========================
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 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.

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 <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 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
=====

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

       extensions = [..., 'sphinxfeed']

#. 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

#. Optionally use the following metadata fields:

   - date (or any other name configured using feed_field_name)
   - author
   - 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 -m "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.
