docs/main/FeedStream.rst | 89 +++++++++++++++++++++++++++++++++++++++++++
docs/main/FeedWidget.rst | 95 ++++++++++++++++++++++++++++++++++++++++++++++
docs/main/Feeds.rst | 97 +----------------------------------------------
3 files changed, 188 insertions(+), 93 deletions(-)
New commits:
commit 6a7b5cbd8122f2ea27a9e456e964721b5ed12a24
Author: Luke Macken <lmacken(a)redhat.com>
Date: Mon Feb 7 20:21:39 2011 -0500
Document our moksha feed aggregator and new post-processing feed hooks
diff --git a/docs/main/FeedStream.rst b/docs/main/FeedStream.rst
new file mode 100644
index 0000000..89a6741
--- /dev/null
+++ b/docs/main/FeedStream.rst
@@ -0,0 +1,89 @@
+The Moksha Feed Stream
+----------------------
+
+The ``moksha.feeds`` app provides a moksha Producer_ that will handle
+automatically fetching, parsing, and caching feeds. Once installed, the Moksha Feed Stream will be run by the MokshaHub_.
+
+It will automatically fetch all feeds used by the Moksha :class:`Feed` object,
+as well as all feeds listed in a ``feeds.txt`` file, if one exists.
+
+Installing the ``moksha.feeds`` app
+-----------------------------------
+
+Currently the easiest way to install the app is from the moksha git repository
+
+.. code-block:: bash
+
+ $ git clone git://git.fedorahosted.org/git/moksha
+ $ cd moksha/apps/feeds
+
+
+From here, if you are running Moksha from an RPM installation:
+
+.. code-block:: bash
+
+ $ paver reinstall
+
+Or, if you're running from a virtualenv installation:
+
+.. code-block:: bash
+
+ $ paver install
+
+Configuring the Moksha Feed Aggregator
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+The feed app can be configured with the following options in your config file:
+
+.. code-block:: python
+
+ # Number of seconds between polling feeds
+ feed.poll_frequency = 900
+
+ # Where to store the feed caches. Defaults to an in-memory cache.
+ #feed_cache = sqlite:///%(here)s/feeds.db
+
+ # Max age (in seconds) of each feed in the cache
+ feed.max_age = 300
+
+ # Timeout in seconds for the web request
+ feed.timeout = 60
+
+ # The number of simultaneous connections
+ feed.deferred_groups = 3
+
+
+Performing post-processing on feed entries
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+All new feed entries for a given ``$URL`` are sent to the ``moksha.feeds.$URL``
+message topic. By default only the title and url of the entry are sent to the
+message broker. However, Moksha provides a simple API for writing
+post-processing plug-ins that can modify the feed before it is sent to any
+:doc:`LiveWidgets` or :doc:`Consumers`.
+
+.. code-block:: python
+
+ def process_feed_entry(entry):
+ """ This method is called by the Moksha Feed Streamer with each feed entry.
+
+ Here is where we do post-processing on the entry before it gets serialized
+ to JSON and send to our message broker, and then the users.
+
+ :entry: A :mod:`feedparser` feed object
+ """
+ return dict(author=entry['author'],
+ author_link=entry['author_detail']['href'],
+ content=entry['content'][0]['value'],
+ author_avatar=entry['source']['icon'])
+
+Then you simply plug this method into the ``moksha.feeds.post_processor`` entry-point:
+
+.. code-block:: python
+
+ setup(...
+ entry_points="""
+ [moksha.feeds.post_processor]
+ myfeedprocessor = myapp.feed_processor:process_feed_entry
+ """
+ )
diff --git a/docs/main/FeedWidget.rst b/docs/main/FeedWidget.rst
new file mode 100644
index 0000000..4838e8c
--- /dev/null
+++ b/docs/main/FeedWidget.rst
@@ -0,0 +1,95 @@
+The Moksha Feed Widget
+----------------------
+
+.. autoclass:: moksha.api.widgets.feed.Feed
+ :members:
+
+.. widgetbrowser:: moksha.widgets.demos.FeedDemo
+ :tabs: demo, source, template
+ :size: large
+
+Using the Feed widget
+~~~~~~~~~~~~~~~~~~~~~
+
+.. code-block:: python
+
+ from moksha.api.widgets.feed import Feed
+ feed = Feed('myfeed')
+ feed(url='http://lewk.org/rss')
+
+Rendering a url with the Feed object
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+.. code-block:: python
+
+ feed = Feed('myfeed')
+ feed(url='http://lewk.org/rss')
+
+.. note::
+ Usually you would instantiate a single Feed object somewhere in your
+ project, and just call it with a `url` when rendering it in your templates.
+
+Subclassing
+~~~~~~~~~~~
+
+.. code-block:: python
+
+ class MyFeed(Feed):
+ url = 'http://foo.com/feed.xml'
+
+ myfeed = MyFeed()
+ myfeed() # renders the widget, usually done in the template
+
+As ToscaWidget children
+~~~~~~~~~~~~~~~~~~~~~~~
+
+By defining your Feeds as children to a widget, ToscaWidgets will automatically
+handle setting a unique id for your Feed object, as well as giving you the
+ability access it in your template from the `c` context object.
+
+.. code-block:: python
+
+ from tw.api import Widget
+ from moksha.api.widgets.feed import Feed
+
+ class MyWidget(Widget):
+ myfeedurl = 'http://foo.com/feed.xml'
+ children = [Feed('myfeed', url=myfeedurl)]
+ template = "${c.myfeed()}"
+
+As a generator
+~~~~~~~~~~~~~~
+
+.. code-block:: python
+
+ feed = Feed('myfeed', url='http://foo.com/feed.xml')
+ print '%d entries' % feed.num_entries()
+ for entry in feed.iterentries():
+ print entry.title
+
+Using the moksha feed cache by hand
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+The moksha Feed widget automatically handles fetching and caching your feeds
+using the global moksha feed cache. The moksha middleware automatically
+handles setting up this object, and making it available for all of the
+applications and widgets. Moksha utilizes `Doug Hellmann's feedcache module <http://www.doughellmann.com/projects/feedcache>`_, which intelligently handles
+all of the hard work for us.
+
+Here is an example of using the feed cache to manually fetch a feed.
+
+
+.. code-block:: python
+
+ import moksha
+ feed = moksha.feed_cache.fetch('http://foo.com/feed.xml')
+ for entry in feed.entries:
+ print entry
+
+.. note::
+ The moksha.feed_cache object is a
+ :class:`paste.registry.StackedObjectProxy` instance, and is setup by the
+ :class:`moksha.middleware.MokshaMiddleware` before each request reaches
+ your application. Thus, it only works during requests and cannot be
+ used without using the MokshaMiddleware.
+
diff --git a/docs/main/Feeds.rst b/docs/main/Feeds.rst
index b6e7bdb..24256b2 100644
--- a/docs/main/Feeds.rst
+++ b/docs/main/Feeds.rst
@@ -11,97 +11,8 @@ When used within the Moksha Platform, the Feed object will utilize the central
global `moksha.feed_cache`. When used outside of the platform, it will
automatically use a local sqlite database cache.
-The Moksha Feed Widget
-----------------------
+.. toctree::
+ :maxdepth: 2
-.. autoclass:: moksha.api.widgets.feed.Feed
- :members:
-
-.. widgetbrowser:: moksha.widgets.demos.FeedDemo
- :tabs: demo, source, template
- :size: large
-
-Using the Feed widget
-~~~~~~~~~~~~~~~~~~~~~
-
-.. code-block:: python
-
- from moksha.api.widgets.feed import Feed
- feed = Feed('myfeed')
- feed(url='http://lewk.org/rss')
-
-Rendering a url with the Feed object
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-.. code-block:: python
-
- feed = Feed('myfeed')
- feed(url='http://lewk.org/rss')
-
-.. note::
- Usually you would instantiate a single Feed object somewhere in your
- project, and just call it with a `url` when rendering it in your templates.
-
-Subclassing
-~~~~~~~~~~~
-
-.. code-block:: python
-
- class MyFeed(Feed):
- url = 'http://foo.com/feed.xml'
-
- myfeed = MyFeed()
- myfeed() # renders the widget, usually done in the template
-
-As ToscaWidget children
-~~~~~~~~~~~~~~~~~~~~~~~
-
-By defining your Feeds as children to a widget, ToscaWidgets will automatically
-handle setting a unique id for your Feed object, as well as giving you the
-ability access it in your template from the `c` context object.
-
-.. code-block:: python
-
- from tw.api import Widget
- from moksha.api.widgets.feed import Feed
-
- class MyWidget(Widget):
- myfeedurl = 'http://foo.com/feed.xml'
- children = [Feed('myfeed', url=myfeedurl)]
- template = "${c.myfeed()}"
-
-As a generator
-~~~~~~~~~~~~~~
-
-.. code-block:: python
-
- feed = Feed('myfeed', url='http://foo.com/feed.xml')
- print '%d entries' % feed.num_entries()
- for entry in feed.iterentries():
- print entry.title
-
-Using the moksha feed cache by hand
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-The moksha Feed widget automatically handles fetching and caching your feeds
-using the global moksha feed cache. The moksha middleware automatically
-handles setting up this object, and making it available for all of the
-applications and widgets. Moksha utilizes `Doug Hellmann's feedcache module <http://www.doughellmann.com/projects/feedcache>`_, which intelligently handles
-all of the hard work for us.
-
-Here is an example of using the feed cache to manually fetch a feed.
-
-
-.. code-block:: python
-
- import moksha
- feed = moksha.feed_cache.fetch('http://foo.com/feed.xml')
- for entry in feed.entries:
- print entry
-
-.. note::
- The moksha.feed_cache object is a
- :class:`paste.registry.StackedObjectProxy` instance, and is setup by the
- :class:`moksha.middleware.MokshaMiddleware` before each request reaches
- your application. Thus, it only works during requests and cannot be
- used without using the MokshaMiddleware.
+ FeedWidget
+ FeedStream
