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 8a388fd70c..979c1867d1 100644
--- a/docs/ref/utils.txt
+++ b/docs/ref/utils.txt
@@ -229,6 +229,17 @@ SyndicationFeed
.. class:: SyndicationFeed
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])
+
+ 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])
@@ -241,12 +252,12 @@ SyndicationFeed
.. method:: root_attributes()
Return extra attributes to place on the root (i.e. feed/channel)
- element. Called from write().
+ element. Called from ``write()``.
.. method:: add_root_elements(handler)
Add elements in the root (i.e. feed/channel) element.
- Called from write().
+ Called from ``write()``.
.. method:: item_attributes(item)
@@ -290,6 +301,13 @@ Rss201rev2Feed
Spec: http://blogs.law.harvard.edu/tech/rss
+RssUserland091Feed
+------------------
+
+.. class:: RssUserland091Feed(RssFeed)
+
+ Spec: http://backend.userland.com/rss091
+
Atom1Feed
---------