sphinxfeed-lsaffre 0.3.1__tar.gz

sphinxfeed_lsaffre-0.3.1/.gitignore

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

sphinxfeed_lsaffre-0.3.1/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.

sphinxfeed_lsaffre-0.3.1/PKG-INFO

@@ -0,0 +1,126 @@
+Metadata-Version: 2.3
+Name: sphinxfeed-lsaffre
+Version: 0.3.1
+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: Topic :: Documentation
+Classifier: Topic :: Utilities
+Requires-Dist: feedgen
+Requires-Dist: python-dateutil
+Requires-Dist: sphinx
+Description-Content-Type: text/x-rst
+
+==========================
+The ``sphinxfeed`` 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.
+
+
+Installation
+============
+
+Soon 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 sphinxfeed
+
+Run the test suite::
+
+  $ pytest
+
+Release a new version to PyPI::
+
+  $ python -m build
+  $ twine check --strict dist/*
+  $ twine upload dist/*
+
+The ``twine upload`` step requires authentication credentials in your
+`~/.pypirc` file.

sphinxfeed_lsaffre-0.3.1/README.rst

@@ -0,0 +1,80 @@
+==========================
+The ``sphinxfeed`` 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.
+
+
+Installation
+============
+
+Soon 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 sphinxfeed
+
+Run the test suite::
+
+  $ pytest
+
+Release a new version to PyPI::
+
+  $ python -m build
+  $ twine check --strict dist/*
+  $ twine upload dist/*
+
+The ``twine upload`` step requires authentication credentials in your
+`~/.pypirc` file.

sphinxfeed_lsaffre-0.3.1/pyproject.toml

@@ -0,0 +1,55 @@
+[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"}
+
+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",
+    "Topic :: Documentation",
+    "Topic :: Utilities",
+]
+
+dependencies = [
+    "feedgen",
+    "python-dateutil",
+    "Sphinx",
+]
+
+[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]
+packages = ["sphinxfeed"]
+
+[tool.hatch.build]
+dev-mode-dirs = ["."]

sphinxfeed_lsaffre-0.3.1/sphinxfeed.py

@@ -0,0 +1,178 @@
+# This application is derived from Dan Mackinlay's sphinxcontrib.feed package.
+# The original can be found at http://bitbucket.org/birkenfeld/sphinx-contrib/src/tip/feed/
+"""
+See https://github.com/lsaffre/sphinxfeed
+"""
+
+__version__ = '0.3.1'
+
+import os.path
+import time
+from datetime import datetime
+from dateutil.tz import tzlocal
+from sphinx.util.logging import getLogger
+
+from feedgen.feed import FeedGenerator
+from feedgen.feed import FeedEntry
+
+doc_trees = []  # for atelier
+logger = getLogger(__name__)
+
+
+def parse_pubdate(pubdate):
+    # tz = "+0002"
+    # chunks = pubdate.split()
+    # if len(chunks) == 1:
+    #     chunks.append("23:59")
+    # if len(chunks) == 2:
+    #     chunks.append(tz)
+    # fmt = '%Y-%m-%d %H:%M %Z'
+    # return time.strptime(' '.join(chunks), fmt)
+    fmt = '%Y-%m-%d %H:%M'
+    try:
+        date = time.strptime(pubdate, fmt)
+    except ValueError:
+        date = time.strptime(pubdate + " 23:59", fmt)
+    return date
+
+
+def setup(app):
+    """ see: http://sphinx.pocoo.org/ext/appapi.html
+        this is the primary extension point for Sphinx
+    """
+    from sphinx.application import Sphinx
+    if not isinstance(app, Sphinx): return
+    app.add_config_value('feed_base_url', '', 'html')
+    app.add_config_value('feed_description', '', 'html')
+    app.add_config_value('feed_author', '', 'html')
+    app.add_config_value('feed_field_name', 'Publish Date', 'env')
+    app.add_config_value('feed_filename', 'rss.xml', 'html')
+    app.add_config_value('feed_use_atom', False, 'html')
+    app.add_config_value('use_dirhtml', False, 'html')
+
+    app.connect('html-page-context', create_feed_item)
+    app.connect('build-finished', emit_feed)
+    app.connect('builder-inited', create_feed_container)
+
+    #env.process_metadata deletes most of the docinfo, and dates
+    #in particular.
+
+
+def create_feed_container(app):
+    #from feedformatter import Feed
+    feed = FeedGenerator()
+    feed.title(app.config.project)
+    feed.link(href=app.config.feed_base_url)
+    if app.config.feed_use_atom:
+        feed.id(app.config.feed_base_url)
+    feed.author({'name': app.config.feed_author})
+    feed.description(app.config.feed_description)
+
+    if app.config.language:
+        feed.language(app.config.language)
+    if app.config.copyright:
+        feed.copyright(app.config.copyright)
+    app.builder.env.feed_feed = feed
+    if not hasattr(app.builder.env, 'feed_items'):
+        app.builder.env.feed_items = {}
+
+
+def create_feed_item(app, pagename, templatename, ctx, doctree):
+    """ Here we have access to nice HTML fragments to use in, say, an RSS feed.
+    """
+
+    env = app.builder.env
+    metadata = app.builder.env.metadata.get(pagename, {})
+
+    pubDate = metadata.get(app.config.feed_field_name, None)
+    if not pubDate:
+        return
+
+    pubDate = parse_pubdate(pubDate)
+
+    if pubDate > time.localtime():
+        logger.warning("Skipping %s, publish date is in the future: %s", pagename, pubDate)
+        return
+
+    if not ctx.get('body') or not ctx.get('title'):
+        return
+
+    pubDate = datetime.fromtimestamp(time.mktime(pubDate))
+    pubDate = pubDate.replace(tzinfo=tzlocal())
+
+    item = FeedEntry()
+    item.title(ctx.get('title'))
+    href = app.config.feed_base_url + '/' + ctx['current_page_name']
+    if not app.config.use_dirhtml:
+        href += ctx['file_suffix']
+    item.link(href=href)
+    if app.config.feed_use_atom:
+        item.id(href)
+    item.description(ctx.get('body'))
+    item.published(pubDate)
+
+    if author := metadata.get('author'):
+        # author may be a str (in field list/frontmatter) or a dict (expected by feedgen)
+        if isinstance (author, str):
+            author = {'name': author}
+        item.author(author)
+    if cat := metadata.get("category", None):
+        item.category(term=cat)
+    if tags := metadata.get("tags", None):
+        # tags may be a str (in field list/frontmatter), or a list (from sphinx-tags extension)
+        if isinstance(tags, str):
+            tags = tags.split()
+        for tag in tags:
+            item.category(term=tag)
+
+    env.feed_items[pagename] = item
+
+    #Additionally, we might like to provide our templates with a way to link to the rss output file
+    ctx['rss_link'] = app.config.feed_base_url + '/' + app.config.feed_filename
+
+
+def emit_feed(app, exc):
+    ordered_items = list(app.builder.env.feed_items.values())
+    feed = app.builder.env.feed_feed
+    # ordered_items.sort(key=lambda x: x['pubDate'], reverse=True)
+    ordered_items.sort(key=lambda x: x.published())
+    for item in ordered_items:
+        feed.add_entry(item)  # prepends the item
+        # for k, v in item.items():
+        #     getattr(e, k)(v)
+
+    path = os.path.join(app.builder.outdir, app.config.feed_filename)
+
+    # print(20190315, path)
+    if app.config.feed_use_atom:
+        feed.atom_file(path)
+    else:
+        feed.rss_file(path)
+
+    return
+    # LS 20180204 The following code (pickle the environment and check
+    # consistency at this point) caused an error when also bibtex was
+    # installed. I deactivated it since I don't know why it's needed.
+
+    from os import path
+    from sphinx.application import ENV_PICKLE_FILENAME
+    from sphinx.util.console import bold
+    # save the environment
+    builder = app.builder
+    builder.info(bold('pickling environment... '), nonl=True)
+    builder.env.topickle(path.join(builder.doctreedir, ENV_PICKLE_FILENAME))
+    builder.info('done')
+
+    # global actions
+    builder.info(bold('checking consistency... '), nonl=True)
+    builder.env.check_consistency()
+    builder.info('done')
+
+
+## Tests
+
+# ... TODO
+
+if __name__ == '__main__':
+    import unittest
+    unittest.main()