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.
git-svn-id: http://code.djangoproject.com/svn/django/trunk@15739 bcc190cf-cafb-0310-a4f2-bffc1f526a37
This commit is contained in:
parent
136930085b
commit
4e76f0f793
|
@ -93,20 +93,20 @@ Note:
|
||||||
|
|
||||||
* The Feed class subclasses :class:`django.contrib.syndication.views.Feed`.
|
* 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,
|
standard RSS ``<title>``, ``<link>`` and ``<description>`` elements,
|
||||||
respectively.
|
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
|
should be included in the feed as ``<item>`` elements. Although this
|
||||||
example returns ``NewsItem`` objects using Django's
|
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
|
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.
|
return any type of object you want.
|
||||||
|
|
||||||
* If you're creating an Atom feed, rather than an RSS feed, set the
|
* 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.
|
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>``,
|
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.
|
into those elements.
|
||||||
|
|
||||||
* For the contents of ``<title>`` and ``<description>``, Django tries
|
* 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
|
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
|
optional; by default, the unicode representation of the object is used for
|
||||||
both.
|
both.
|
||||||
|
|
||||||
|
@ -128,7 +128,7 @@ into those elements.
|
||||||
rendered for each item and are passed two template context variables:
|
rendered for each item and are passed two template context variables:
|
||||||
|
|
||||||
* ``{{ obj }}`` -- The current object (one of whichever objects you
|
* ``{{ 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
|
* ``{{ site }}`` -- A :class:`django.contrib.sites.models.Site` object
|
||||||
representing the current site. This is useful for ``{{ site.domain
|
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.
|
See `a complex example`_ below that uses a description template.
|
||||||
|
|
||||||
* To specify the contents of ``<link>``, you have two options. For each item
|
* To specify the contents of ``<link>``, you have two options. For each item
|
||||||
in :meth:`items()`, Django first tries calling the
|
in ``items()``, Django first tries calling the
|
||||||
:meth:`item_link()` method on the
|
``item_link()`` method on the
|
||||||
:class:`~django.contrib.syndication.views.Feed` class. In a similar way to
|
:class:`~django.contrib.syndication.views.Feed` class. In a similar way to
|
||||||
the title and description, it is passed it a single parameter,
|
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
|
``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
|
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
|
are responsible for doing all necessary URL quoting and conversion to
|
||||||
ASCII inside the method itself.
|
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()),
|
(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.
|
method along with the request object.
|
||||||
|
|
||||||
.. versionchanged:: 1.2
|
.. 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]
|
return Crime.objects.filter(beat=obj).order_by('-crime_date')[:30]
|
||||||
|
|
||||||
To generate the feed's ``<title>``, ``<link>`` and ``<description>``, Django
|
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
|
the previous example, they were simple string class attributes, but this example
|
||||||
illustrates that they can be either strings *or* methods. For each of
|
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:
|
algorithm:
|
||||||
|
|
||||||
* First, it tries to call a method, passing the ``obj`` argument, where
|
* 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 tries to call a method with no arguments.
|
||||||
|
|
||||||
* Failing that, it uses the class attribute.
|
* Failing that, it uses the class attribute.
|
||||||
|
|
||||||
Also note that :meth:`items()` also follows the same algorithm -- first, it
|
Also note that ``items()`` also follows the same algorithm -- first, it
|
||||||
tries :meth:`items(obj)`, then :meth:`items()`, then finally an :attr:`items`
|
tries ``items(obj)``, then ``items()``, then finally an ``items``
|
||||||
class attribute (which should be a list).
|
class attribute (which should be a list).
|
||||||
|
|
||||||
We are using a template for the item descriptions. It can be very simple:
|
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
|
To specify enclosures, such as those used in creating podcast feeds, use the
|
||||||
:attr:`item_enclosure_url`, :attr:`item_enclosure_length` and
|
``item_enclosure_url``, ``item_enclosure_length`` and
|
||||||
:attr:`item_enclosure_mime_type` hooks. See the ``ExampleFeed`` class below for
|
``item_enclosure_mime_type`` hooks. See the ``ExampleFeed`` class below for
|
||||||
usage examples.
|
usage examples.
|
||||||
|
|
||||||
Language
|
Language
|
||||||
|
@ -274,9 +274,9 @@ comes directly from your :setting:`LANGUAGE_CODE` setting.
|
||||||
URLs
|
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.
|
: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
|
the syndication framework will insert the domain of the current site, according
|
||||||
to your :setting:`SITE_ID setting <SITE_ID>`.
|
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
|
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
|
feeds. That's easy to do with Django: Just create a subclass of your
|
||||||
:class:`~django.contrib.syndication.views.Feed`
|
: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.
|
URLconf to add the extra versions.
|
||||||
|
|
||||||
Here's a full example::
|
Here's a full example::
|
||||||
|
@ -312,18 +312,18 @@ Here's a full example::
|
||||||
subtitle = RssSiteNewsFeed.description
|
subtitle = RssSiteNewsFeed.description
|
||||||
|
|
||||||
.. Note::
|
.. Note::
|
||||||
In this example, the RSS feed uses a :attr:`description` while the Atom
|
In this example, the RSS feed uses a ``description`` while the Atom
|
||||||
feed uses a :attr:`subtitle`. That's because Atom feeds don't provide for
|
feed uses a ``subtitle``. That's because Atom feeds don't provide for
|
||||||
a feed-level "description," but they *do* provide for a "subtitle."
|
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*
|
: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
|
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
|
In the above example, we simply set the Atom feed's ``subtitle`` to the
|
||||||
RSS feed's :attr:`description`, because it's quite short already.
|
RSS feed's ``description``, because it's quite short already.
|
||||||
|
|
||||||
And the accompanying URLconf::
|
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``
|
also create custom feed generator subclasses for use with the ``feed_type``
|
||||||
``Feed`` option.
|
``Feed`` option.
|
||||||
|
|
||||||
|
.. currentmodule:: django.utils.feedgenerator
|
||||||
|
|
||||||
``SyndicationFeed`` classes
|
``SyndicationFeed`` classes
|
||||||
---------------------------
|
---------------------------
|
||||||
|
|
||||||
The :mod:`~django.utils.feedgenerator` module contains a base class:
|
The :mod:`~django.utils.feedgenerator` module contains a base class:
|
||||||
|
|
||||||
.. class:: django.utils.feedgenerator.SyndicationFeed
|
* :class:`django.utils.feedgenerator.SyndicationFeed`
|
||||||
|
|
||||||
and several subclasses:
|
and several subclasses:
|
||||||
|
|
||||||
.. class:: django.utils.feedgenerator.RssUserland091Feed
|
* :class:`django.utils.feedgenerator.RssUserland091Feed`
|
||||||
.. class:: django.utils.feedgenerator.Rss201rev2Feed
|
* :class:`django.utils.feedgenerator.Rss201rev2Feed`
|
||||||
.. class:: django.utils.feedgenerator.Atom1Feed
|
* :class:`django.utils.feedgenerator.Atom1Feed`
|
||||||
|
|
||||||
Each of these three classes knows how to render a certain type of feed as XML.
|
Each of these three classes knows how to render a certain type of feed as XML.
|
||||||
They share this interface:
|
They share this interface:
|
||||||
|
|
||||||
.. method:: SyndicationFeed.__init__(**kwargs)
|
:meth:`.SyndicationFeed.__init__`
|
||||||
|
|
||||||
Initialize the feed with the given dictionary of metadata, which applies to
|
Initialize the feed with the given dictionary of metadata, which applies to
|
||||||
the entire feed. Required keyword arguments are:
|
the entire feed. Required keyword arguments are:
|
||||||
|
|
||||||
|
@ -825,8 +826,7 @@ They share this interface:
|
||||||
All parameters should be Unicode objects, except ``categories``, which
|
All parameters should be Unicode objects, except ``categories``, which
|
||||||
should be a sequence of Unicode objects.
|
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.
|
Add an item to the feed with the given parameters.
|
||||||
|
|
||||||
Required keyword arguments are:
|
Required keyword arguments are:
|
||||||
|
@ -856,12 +856,10 @@ They share this interface:
|
||||||
* ``enclosure`` should be an instance of ``feedgenerator.Enclosure``.
|
* ``enclosure`` should be an instance of ``feedgenerator.Enclosure``.
|
||||||
* ``categories`` should be a sequence of Unicode objects.
|
* ``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.
|
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.
|
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::
|
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
|
.. _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
|
.. _Python datetime object: http://docs.python.org/library/datetime.html#datetime-objects
|
||||||
|
|
||||||
|
.. currentmodule:: django.contrib.syndication
|
||||||
|
|
||||||
Custom feed generators
|
Custom feed generators
|
||||||
----------------------
|
----------------------
|
||||||
|
|
||||||
|
|
|
@ -229,6 +229,17 @@ SyndicationFeed
|
||||||
.. class:: 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])
|
||||||
|
|
||||||
|
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])
|
||||||
|
|
||||||
|
@ -241,12 +252,12 @@ SyndicationFeed
|
||||||
.. method:: root_attributes()
|
.. method:: root_attributes()
|
||||||
|
|
||||||
Return extra attributes to place on the root (i.e. feed/channel)
|
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)
|
.. method:: add_root_elements(handler)
|
||||||
|
|
||||||
Add elements in the root (i.e. feed/channel) element.
|
Add elements in the root (i.e. feed/channel) element.
|
||||||
Called from write().
|
Called from ``write()``.
|
||||||
|
|
||||||
.. method:: item_attributes(item)
|
.. method:: item_attributes(item)
|
||||||
|
|
||||||
|
@ -290,6 +301,13 @@ Rss201rev2Feed
|
||||||
|
|
||||||
Spec: http://blogs.law.harvard.edu/tech/rss
|
Spec: http://blogs.law.harvard.edu/tech/rss
|
||||||
|
|
||||||
|
RssUserland091Feed
|
||||||
|
------------------
|
||||||
|
|
||||||
|
.. class:: RssUserland091Feed(RssFeed)
|
||||||
|
|
||||||
|
Spec: http://backend.userland.com/rss091
|
||||||
|
|
||||||
Atom1Feed
|
Atom1Feed
|
||||||
---------
|
---------
|
||||||
|
|
||||||
|
|
Loading…
Reference in New Issue