test0908
/
django
1
0
Fork 0
Code Issues Pull Requests Projects Releases Wiki Activity

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:
Gabriel Hurley 2011-03-03 22:20:54 +00:00
parent 136930085b
commit 4e76f0f793
2 changed files with 63 additions and 45 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

86
docs/ref/contrib/syndication.txt
View File

@ -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
----------------------

22
docs/ref/utils.txt
View File

@ -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
---------