[1.2.X] Fixed #15504 -- Cleaned up contrib.syndication and contrib.utils.feedgenerator docs. Corrected numerous reST problems, removed duplicate method declarations, corrected method signatures, etc. Thanks to slinkp for the report.

Backport of [15739] from trunk.

git-svn-id: http://code.djangoproject.com/svn/django/branches/releases/1.2.X@15740 bcc190cf-cafb-0310-a4f2-bffc1f526a37

2 files changed, 84 insertions, 68 deletions

diff --git a/docs/ref/contrib/syndication.txt b/docs/ref/contrib/syndication.txt
index 04f14b5531..8666023923 100644
--- a/docs/ref/contrib/syndication.txt
+++ b/docs/ref/contrib/syndication.txt
@@ -93,20 +93,20 @@ Note:
 
 * The Feed class subclasses :class:`django.contrib.syndication.views.Feed`.
 
-* :attr:`title`, :attr:`link` and :attr:`description` correspond to the
+* ``title``, ``link`` and ``description` correspond to the
   standard RSS ``<title>``, ``<link>`` and ``<description>`` elements,
   respectively.
 
-* :meth:`items()` is, simply, a method that returns a list of objects that
+* ``items()`` is, simply, a method that returns a list of objects that
   should be included in the feed as ``<item>`` elements. Although this
   example returns ``NewsItem`` objects using Django's
-  :doc:`object-relational mapper </ref/models/querysets>`, :meth:`items()`
+  :doc:`object-relational mapper </ref/models/querysets>`, ``items()``
   doesn't have to return model instances. Although you get a few bits of
-  functionality "for free" by using Django models, :meth:`items()` can
+  functionality "for free" by using Django models, ``items()`` can
   return any type of object you want.
 
 * If you're creating an Atom feed, rather than an RSS feed, set the
-  :attr:`subtitle` attribute instead of the :attr:`description` attribute.
+  ``subtitle`` attribute instead of the ``description`` attribute.
   See `Publishing Atom and RSS feeds in tandem`_, later, for an example.
 
 One thing is left to do. In an RSS feed, each ``<item>`` has a ``<title>``,
@@ -114,9 +114,9 @@ One thing is left to do. In an RSS feed, each ``<item>`` has a ``<title>``,
 into those elements.
 
     * For the contents of ``<title>`` and ``<description>``, Django tries
-      calling the methods :meth:`item_title()` and :meth:`item_description()` on
+      calling the methods ``item_title()`` and ``item_description()`` on
       the :class:`~django.contrib.syndication.views.Feed` class. They are passed
-      a single parameter, :attr:`item`, which is the object itself. These are
+      a single parameter, ``item``, which is the object itself. These are
       optional; by default, the unicode representation of the object is used for
       both.
 
@@ -128,7 +128,7 @@ into those elements.
       rendered for each item and are passed two template context variables:
 
          * ``{{ obj }}`` -- The current object (one of whichever objects you
-           returned in :meth:`items()`).
+           returned in ``items()``).
 
          * ``{{ site }}`` -- A :class:`django.contrib.sites.models.Site` object
            representing the current site. This is useful for ``{{ site.domain
@@ -141,15 +141,15 @@ into those elements.
       See `a complex example`_ below that uses a description template.
 
     * To specify the contents of ``<link>``, you have two options. For each item
-      in :meth:`items()`, Django first tries calling the
-      :meth:`item_link()` method on the
+      in ``items()``, Django first tries calling the
+      ``item_link()`` method on the
       :class:`~django.contrib.syndication.views.Feed` class. In a similar way to
       the title and description, it is passed it a single parameter,
-      :attr:`item`. If that method doesn't exist, Django tries executing a
+      ``item``. If that method doesn't exist, Django tries executing a
       ``get_absolute_url()`` method on that object. Both
-      :meth:`get_absolute_url()` and :meth:`item_link()` should return the
+      ``get_absolute_url()`` and ``item_link()`` should return the
       item's URL as a normal Python string. As with ``get_absolute_url()``, the
-      result of :meth:`item_link()` will be included directly in the URL, so you
+      result of ``item_link()`` will be included directly in the URL, so you
       are responsible for doing all necessary URL quoting and conversion to
       ASCII inside the method itself.
 
@@ -177,7 +177,7 @@ These can be matched with a :doc:`URLconf </topics/http/urls>` line such as::
 
     (r'^beats/(?P<beat_id>\d+)/rss/$', BeatFeed()),
 
-Like a view, the arguments in the URL are passed to the :meth:`get_object()`
+Like a view, the arguments in the URL are passed to the ``get_object()``
 method along with the request object.
 
 .. versionchanged:: 1.2
@@ -207,21 +207,21 @@ Here's the code for these beat-specific feeds::
             return Crime.objects.filter(beat=obj).order_by('-crime_date')[:30]
 
 To generate the feed's ``<title>``, ``<link>`` and ``<description>``, Django
-uses the :meth:`title()`, :meth:`link()` and :meth:`description()` methods. In
+uses the ``title()``, ``link()`` and ``description()`` methods. In
 the previous example, they were simple string class attributes, but this example
 illustrates that they can be either strings *or* methods. For each of
-:attr:`title`, :attr:`link` and :attr:`description`, Django follows this
+``title``, ``link`` and ``description``, Django follows this
 algorithm:
 
     * First, it tries to call a method, passing the ``obj`` argument, where
-      ``obj`` is the object returned by :meth:`get_object()`.
+      ``obj`` is the object returned by ``get_object()``.
 
     * Failing that, it tries to call a method with no arguments.
 
     * Failing that, it uses the class attribute.
 
-Also note that :meth:`items()` also follows the same algorithm -- first, it
-tries :meth:`items(obj)`, then :meth:`items()`, then finally an :attr:`items`
+Also note that ``items()`` also follows the same algorithm -- first, it
+tries ``items(obj)``, then ``items()``, then finally an ``items``
 class attribute (which should be a list).
 
 We are using a template for the item descriptions. It can be very simple:
@@ -260,8 +260,8 @@ Enclosures
 ----------
 
 To specify enclosures, such as those used in creating podcast feeds, use the
-:attr:`item_enclosure_url`, :attr:`item_enclosure_length` and
-:attr:`item_enclosure_mime_type` hooks. See the ``ExampleFeed`` class below for
+``item_enclosure_url``, ``item_enclosure_length`` and
+``item_enclosure_mime_type`` hooks. See the ``ExampleFeed`` class below for
 usage examples.
 
 Language
@@ -274,9 +274,9 @@ comes directly from your :setting:`LANGUAGE_CODE` setting.
 URLs
 ----
 
-The :attr:`link` method/attribute can return either an absolute path (e.g.
+The ``link`` method/attribute can return either an absolute path (e.g.
 :file:`"/blog/"`) or a URL with the fully-qualified domain and protocol (e.g.
-``"http://www.example.com/blog/"``). If :attr:`link` doesn't return the domain,
+``"http://www.example.com/blog/"``). If ``link`` doesn't return the domain,
 the syndication framework will insert the domain of the current site, according
 to your :setting:`SITE_ID setting <SITE_ID>`.
 
@@ -290,7 +290,7 @@ Publishing Atom and RSS feeds in tandem
 Some developers like to make available both Atom *and* RSS versions of their
 feeds. That's easy to do with Django: Just create a subclass of your
 :class:`~django.contrib.syndication.views.Feed`
-class and set the :attr:`feed_type` to something different. Then update your
+class and set the ``feed_type`` to something different. Then update your
 URLconf to add the extra versions.
 
 Here's a full example::
@@ -312,18 +312,18 @@ Here's a full example::
         subtitle = RssSiteNewsFeed.description
 
 .. Note::
-    In this example, the RSS feed uses a :attr:`description` while the Atom
-    feed uses a :attr:`subtitle`. That's because Atom feeds don't provide for
+    In this example, the RSS feed uses a ``description`` while the Atom
+    feed uses a ``subtitle``. That's because Atom feeds don't provide for
     a feed-level "description," but they *do* provide for a "subtitle."
 
-    If you provide a :attr:`description` in your
+    If you provide a ``description`` in your
     :class:`~django.contrib.syndication.views.Feed` class, Django will *not*
-    automatically put that into the :attr:`subtitle` element, because a
+    automatically put that into the ``subtitle`` element, because a
     subtitle and description are not necessarily the same thing. Instead, you
-    should define a :attr:`subtitle` attribute.
+    should define a ``subtitle`` attribute.
 
-    In the above example, we simply set the Atom feed's :attr:`subtitle` to the
-    RSS feed's :attr:`description`, because it's quite short already.
+    In the above example, we simply set the Atom feed's ``subtitle`` to the
+    RSS feed's ``description``, because it's quite short already.
 
 And the accompanying URLconf::
 
@@ -781,24 +781,25 @@ You use this framework on your own, for lower-level feed generation. You can
 also create custom feed generator subclasses for use with the ``feed_type``
 ``Feed`` option.
 
+.. currentmodule:: django.utils.feedgenerator
+
 ``SyndicationFeed`` classes
 ---------------------------
 
 The :mod:`~django.utils.feedgenerator` module contains a base class:
 
-.. class:: django.utils.feedgenerator.SyndicationFeed
+  * :class:`django.utils.feedgenerator.SyndicationFeed`
 
 and several subclasses:
 
-.. class:: django.utils.feedgenerator.RssUserland091Feed
-.. class:: django.utils.feedgenerator.Rss201rev2Feed
-.. class:: django.utils.feedgenerator.Atom1Feed
+  * :class:`django.utils.feedgenerator.RssUserland091Feed`
+  * :class:`django.utils.feedgenerator.Rss201rev2Feed`
+  * :class:`django.utils.feedgenerator.Atom1Feed`
 
 Each of these three classes knows how to render a certain type of feed as XML.
 They share this interface:
 
-.. method:: SyndicationFeed.__init__(**kwargs)
-
+:meth:`.SyndicationFeed.__init__`
     Initialize the feed with the given dictionary of metadata, which applies to
     the entire feed. Required keyword arguments are:
 
@@ -825,8 +826,7 @@ They share this interface:
     All parameters should be Unicode objects, except ``categories``, which
     should be a sequence of Unicode objects.
 
-.. method:: SyndicationFeed.add_item(**kwargs)
-
+:meth:`.SyndicationFeed.add_item`
     Add an item to the feed with the given parameters.
 
     Required keyword arguments are:
@@ -856,12 +856,10 @@ They share this interface:
         * ``enclosure`` should be an instance of ``feedgenerator.Enclosure``.
         * ``categories`` should be a sequence of Unicode objects.
 
-.. method:: SyndicationFeed.write(outfile, encoding)
-
+:meth:`.SyndicationFeed.write`
     Outputs the feed in the given encoding to outfile, which is a file-like object.
 
-.. method:: SyndicationFeed.writeString(encoding)
-
+:meth:`.SyndicationFeed.writeString`
     Returns the feed as a string in the given encoding.
 
 For example, to create an Atom 1.0 feed and print it to standard output::
@@ -888,6 +886,8 @@ For example, to create an Atom 1.0 feed and print it to standard output::
 .. _django/utils/feedgenerator.py: http://code.djangoproject.com/browser/django/trunk/django/utils/feedgenerator.py
 .. _Python datetime object: http://docs.python.org/library/datetime.html#datetime-objects
 
+.. currentmodule:: django.contrib.syndication
+
 Custom feed generators
 ----------------------
 
diff --git a/docs/ref/utils.txt b/docs/ref/utils.txt
index e4ce7c4f86..3fc7a63b6e 100644
--- a/docs/ref/utils.txt
+++ b/docs/ref/utils.txt
@@ -222,49 +222,58 @@ SyndicationFeed
 
 .. class:: SyndicationFeed
 
-Base class for all syndication feeds. Subclasses should provide write().
+    Base class for all syndication feeds. Subclasses should provide write().
+    
+    .. method:: __init__(title, link, description, [language=None, author_email=None, author_name=None, author_link=None, subtitle=None, categories=None, feed_url=None, feed_copyright=None, feed_guid=None, ttl=None, **kwargs])
 
-Methods
-~~~~~~~
+        Initialize the feed with the given dictionary of metadata, which applies
+        to the entire feed.
+        
+        Any extra keyword arguments you pass to ``__init__`` will be stored in
+        ``self.feed``.
+
+        All parameters should be Unicode objects, except ``categories``, which
+        should be a sequence of Unicode objects.
 
-.. method:: add_item(title, link, description, [author_email=None, author_name=None, author_link=None, pubdate=None, comments=None, unique_id=None, enclosure=None, categories=(), item_copyright=None, ttl=None, **kwargs])
+    .. method:: add_item(title, link, description, [author_email=None, author_name=None, author_link=None, pubdate=None, comments=None, unique_id=None, enclosure=None, categories=(), item_copyright=None, ttl=None, **kwargs])
 
-Adds an item to the feed. All args are expected to be Python ``unicode``
-objects except ``pubdate``, which is a ``datetime.datetime`` object, and
-``enclosure``, which is an instance of the ``Enclosure`` class.
+        Adds an item to the feed. All args are expected to be Python ``unicode``
+        objects except ``pubdate``, which is a ``datetime.datetime`` object, and
+        ``enclosure``, which is an instance of the ``Enclosure`` class.
 
-.. method:: num_items()
+    .. method:: num_items()
 
-.. method:: root_attributes()
+    .. method:: root_attributes()
 
-Return extra attributes to place on the root (i.e. feed/channel) element.
-Called from write().
+        Return extra attributes to place on the root (i.e. feed/channel)
+        element. Called from ``write()``.
 
-.. method:: add_root_elements(handler)
+    .. method:: add_root_elements(handler)
 
-Add elements in the root (i.e. feed/channel) element. Called from write().
+        Add elements in the root (i.e. feed/channel) element. Called from
+        ``write()``.
 
-.. method:: item_attributes(item)
+    .. method:: item_attributes(item)
 
-Return extra attributes to place on each item (i.e. item/entry) element.
+        Return extra attributes to place on each item (i.e. item/entry) element.
 
-.. method:: add_item_elements(handler, item)
+    .. method:: add_item_elements(handler, item)
 
-Add elements on each item (i.e. item/entry) element.
+        Add elements on each item (i.e. item/entry) element.
 
-.. method:: write(outfile, encoding)
+    .. method:: write(outfile, encoding)
 
-Outputs the feed in the given encoding to ``outfile``, which is a file-like
-object. Subclasses should override this.
+        Outputs the feed in the given encoding to ``outfile``, which is a
+        file-like object. Subclasses should override this.
 
-.. method:: writeString(encoding)
+    .. method:: writeString(encoding)
 
-Returns the feed in the given encoding as a string.
+        Returns the feed in the given encoding as a string.
 
-.. method:: latest_post_date()
+    .. method:: latest_post_date()
 
-Returns the latest item's ``pubdate``. If none of them have a ``pubdate``,
-this returns the current date/time.
+        Returns the latest item's ``pubdate``. If none of them have a
+        ``pubdate``, this returns the current date/time.
 
 Enclosure
 ---------
@@ -285,6 +294,13 @@ Rss201rev2Feed
 
 Spec: http://blogs.law.harvard.edu/tech/rss
 
+RssUserland091Feed
+------------------
+
+.. class:: RssUserland091Feed(RssFeed)
+
+    Spec: http://backend.userland.com/rss091
+
 Atom1Feed
 ---------