Skip to content
This repository

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
Browse code

Fixed #15504 -- Cleaned up contrib.syndication and contrib.utils.feed…

…generator 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
  • Loading branch information...
commit 4e76f0f79398d7ed7c1fea88b70f846e96c94de5 1 parent 1369300
authored March 03, 2011
86  docs/ref/contrib/syndication.txt
@@ -93,20 +93,20 @@ Note:
93 93
 
94 94
 * The Feed class subclasses :class:`django.contrib.syndication.views.Feed`.
95 95
 
96  
-* :attr:`title`, :attr:`link` and :attr:`description` correspond to the
  96
+* ``title``, ``link`` and ``description` correspond to the
97 97
   standard RSS ``<title>``, ``<link>`` and ``<description>`` elements,
98 98
   respectively.
99 99
 
100  
-* :meth:`items()` is, simply, a method that returns a list of objects that
  100
+* ``items()`` is, simply, a method that returns a list of objects that
101 101
   should be included in the feed as ``<item>`` elements. Although this
102 102
   example returns ``NewsItem`` objects using Django's
103  
-  :doc:`object-relational mapper </ref/models/querysets>`, :meth:`items()`
  103
+  :doc:`object-relational mapper </ref/models/querysets>`, ``items()``
104 104
   doesn't have to return model instances. Although you get a few bits of
105  
-  functionality "for free" by using Django models, :meth:`items()` can
  105
+  functionality "for free" by using Django models, ``items()`` can
106 106
   return any type of object you want.
107 107
 
108 108
 * If you're creating an Atom feed, rather than an RSS feed, set the
109  
-  :attr:`subtitle` attribute instead of the :attr:`description` attribute.
  109
+  ``subtitle`` attribute instead of the ``description`` attribute.
110 110
   See `Publishing Atom and RSS feeds in tandem`_, later, for an example.
111 111
 
112 112
 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>``,
114 114
 into those elements.
115 115
 
116 116
     * For the contents of ``<title>`` and ``<description>``, Django tries
117  
-      calling the methods :meth:`item_title()` and :meth:`item_description()` on
  117
+      calling the methods ``item_title()`` and ``item_description()`` on
118 118
       the :class:`~django.contrib.syndication.views.Feed` class. They are passed
119  
-      a single parameter, :attr:`item`, which is the object itself. These are
  119
+      a single parameter, ``item``, which is the object itself. These are
120 120
       optional; by default, the unicode representation of the object is used for
121 121
       both.
122 122
 
@@ -128,7 +128,7 @@ into those elements.
128 128
       rendered for each item and are passed two template context variables:
129 129
 
130 130
          * ``{{ obj }}`` -- The current object (one of whichever objects you
131  
-           returned in :meth:`items()`).
  131
+           returned in ``items()``).
132 132
 
133 133
          * ``{{ site }}`` -- A :class:`django.contrib.sites.models.Site` object
134 134
            representing the current site. This is useful for ``{{ site.domain
@@ -141,15 +141,15 @@ into those elements.
141 141
       See `a complex example`_ below that uses a description template.
142 142
 
143 143
     * To specify the contents of ``<link>``, you have two options. For each item
144  
-      in :meth:`items()`, Django first tries calling the
145  
-      :meth:`item_link()` method on the
  144
+      in ``items()``, Django first tries calling the
  145
+      ``item_link()`` method on the
146 146
       :class:`~django.contrib.syndication.views.Feed` class. In a similar way to
147 147
       the title and description, it is passed it a single parameter,
148  
-      :attr:`item`. If that method doesn't exist, Django tries executing a
  148
+      ``item``. If that method doesn't exist, Django tries executing a
149 149
       ``get_absolute_url()`` method on that object. Both
150  
-      :meth:`get_absolute_url()` and :meth:`item_link()` should return the
  150
+      ``get_absolute_url()`` and ``item_link()`` should return the
151 151
       item's URL as a normal Python string. As with ``get_absolute_url()``, the
152  
-      result of :meth:`item_link()` will be included directly in the URL, so you
  152
+      result of ``item_link()`` will be included directly in the URL, so you
153 153
       are responsible for doing all necessary URL quoting and conversion to
154 154
       ASCII inside the method itself.
155 155
 
@@ -177,7 +177,7 @@ These can be matched with a :doc:`URLconf </topics/http/urls>` line such as::
177 177
 
178 178
     (r'^beats/(?P<beat_id>\d+)/rss/$', BeatFeed()),
179 179
 
180  
-Like a view, the arguments in the URL are passed to the :meth:`get_object()`
  180
+Like a view, the arguments in the URL are passed to the ``get_object()``
181 181
 method along with the request object.
182 182
 
183 183
 .. versionchanged:: 1.2
@@ -207,21 +207,21 @@ Here's the code for these beat-specific feeds::
207 207
             return Crime.objects.filter(beat=obj).order_by('-crime_date')[:30]
208 208
 
209 209
 To generate the feed's ``<title>``, ``<link>`` and ``<description>``, Django
210  
-uses the :meth:`title()`, :meth:`link()` and :meth:`description()` methods. In
  210
+uses the ``title()``, ``link()`` and ``description()`` methods. In
211 211
 the previous example, they were simple string class attributes, but this example
212 212
 illustrates that they can be either strings *or* methods. For each of
213  
-:attr:`title`, :attr:`link` and :attr:`description`, Django follows this
  213
+``title``, ``link`` and ``description``, Django follows this
214 214
 algorithm:
215 215
 
216 216
     * First, it tries to call a method, passing the ``obj`` argument, where
217  
-      ``obj`` is the object returned by :meth:`get_object()`.
  217
+      ``obj`` is the object returned by ``get_object()``.
218 218
 
219 219
     * Failing that, it tries to call a method with no arguments.
220 220
 
221 221
     * Failing that, it uses the class attribute.
222 222
 
223  
-Also note that :meth:`items()` also follows the same algorithm -- first, it
224  
-tries :meth:`items(obj)`, then :meth:`items()`, then finally an :attr:`items`
  223
+Also note that ``items()`` also follows the same algorithm -- first, it
  224
+tries ``items(obj)``, then ``items()``, then finally an ``items``
225 225
 class attribute (which should be a list).
226 226
 
227 227
 We are using a template for the item descriptions. It can be very simple:
@@ -260,8 +260,8 @@ Enclosures
260 260
 ----------
261 261
 
262 262
 To specify enclosures, such as those used in creating podcast feeds, use the
263  
-:attr:`item_enclosure_url`, :attr:`item_enclosure_length` and
264  
-:attr:`item_enclosure_mime_type` hooks. See the ``ExampleFeed`` class below for
  263
+``item_enclosure_url``, ``item_enclosure_length`` and
  264
+``item_enclosure_mime_type`` hooks. See the ``ExampleFeed`` class below for
265 265
 usage examples.
266 266
 
267 267
 Language
@@ -274,9 +274,9 @@ comes directly from your :setting:`LANGUAGE_CODE` setting.
274 274
 URLs
275 275
 ----
276 276
 
277  
-The :attr:`link` method/attribute can return either an absolute path (e.g.
  277
+The ``link`` method/attribute can return either an absolute path (e.g.
278 278
 :file:`"/blog/"`) or a URL with the fully-qualified domain and protocol (e.g.
279  
-``"http://www.example.com/blog/"``). If :attr:`link` doesn't return the domain,
  279
+``"http://www.example.com/blog/"``). If ``link`` doesn't return the domain,
280 280
 the syndication framework will insert the domain of the current site, according
281 281
 to your :setting:`SITE_ID setting <SITE_ID>`.
282 282
 
@@ -290,7 +290,7 @@ Publishing Atom and RSS feeds in tandem
290 290
 Some developers like to make available both Atom *and* RSS versions of their
291 291
 feeds. That's easy to do with Django: Just create a subclass of your
292 292
 :class:`~django.contrib.syndication.views.Feed`
293  
-class and set the :attr:`feed_type` to something different. Then update your
  293
+class and set the ``feed_type`` to something different. Then update your
294 294
 URLconf to add the extra versions.
295 295
 
296 296
 Here's a full example::
@@ -312,18 +312,18 @@ Here's a full example::
312 312
         subtitle = RssSiteNewsFeed.description
313 313
 
314 314
 .. Note::
315  
-    In this example, the RSS feed uses a :attr:`description` while the Atom
316  
-    feed uses a :attr:`subtitle`. That's because Atom feeds don't provide for
  315
+    In this example, the RSS feed uses a ``description`` while the Atom
  316
+    feed uses a ``subtitle``. That's because Atom feeds don't provide for
317 317
     a feed-level "description," but they *do* provide for a "subtitle."
318 318
 
319  
-    If you provide a :attr:`description` in your
  319
+    If you provide a ``description`` in your
320 320
     :class:`~django.contrib.syndication.views.Feed` class, Django will *not*
321  
-    automatically put that into the :attr:`subtitle` element, because a
  321
+    automatically put that into the ``subtitle`` element, because a
322 322
     subtitle and description are not necessarily the same thing. Instead, you
323  
-    should define a :attr:`subtitle` attribute.
  323
+    should define a ``subtitle`` attribute.
324 324
 
325  
-    In the above example, we simply set the Atom feed's :attr:`subtitle` to the
326  
-    RSS feed's :attr:`description`, because it's quite short already.
  325
+    In the above example, we simply set the Atom feed's ``subtitle`` to the
  326
+    RSS feed's ``description``, because it's quite short already.
327 327
 
328 328
 And the accompanying URLconf::
329 329
 
@@ -781,24 +781,25 @@ You use this framework on your own, for lower-level feed generation. You can
781 781
 also create custom feed generator subclasses for use with the ``feed_type``
782 782
 ``Feed`` option.
783 783
 
  784
+.. currentmodule:: django.utils.feedgenerator
  785
+
784 786
 ``SyndicationFeed`` classes
785 787
 ---------------------------
786 788
 
787 789
 The :mod:`~django.utils.feedgenerator` module contains a base class:
788 790
 
789  
-.. class:: django.utils.feedgenerator.SyndicationFeed
  791
+  * :class:`django.utils.feedgenerator.SyndicationFeed`
790 792
 
791 793
 and several subclasses:
792 794
 
793  
-.. class:: django.utils.feedgenerator.RssUserland091Feed
794  
-.. class:: django.utils.feedgenerator.Rss201rev2Feed
795  
-.. class:: django.utils.feedgenerator.Atom1Feed
  795
+  * :class:`django.utils.feedgenerator.RssUserland091Feed`
  796
+  * :class:`django.utils.feedgenerator.Rss201rev2Feed`
  797
+  * :class:`django.utils.feedgenerator.Atom1Feed`
796 798
 
797 799
 Each of these three classes knows how to render a certain type of feed as XML.
798 800
 They share this interface:
799 801
 
800  
-.. method:: SyndicationFeed.__init__(**kwargs)
801  
-
  802
+:meth:`.SyndicationFeed.__init__`
802 803
     Initialize the feed with the given dictionary of metadata, which applies to
803 804
     the entire feed. Required keyword arguments are:
804 805
 
@@ -825,8 +826,7 @@ They share this interface:
825 826
     All parameters should be Unicode objects, except ``categories``, which
826 827
     should be a sequence of Unicode objects.
827 828
 
828  
-.. method:: SyndicationFeed.add_item(**kwargs)
829  
-
  829
+:meth:`.SyndicationFeed.add_item`
830 830
     Add an item to the feed with the given parameters.
831 831
 
832 832
     Required keyword arguments are:
@@ -856,12 +856,10 @@ They share this interface:
856 856
         * ``enclosure`` should be an instance of ``feedgenerator.Enclosure``.
857 857
         * ``categories`` should be a sequence of Unicode objects.
858 858
 
859  
-.. method:: SyndicationFeed.write(outfile, encoding)
860  
-
  859
+:meth:`.SyndicationFeed.write`
861 860
     Outputs the feed in the given encoding to outfile, which is a file-like object.
862 861
 
863  
-.. method:: SyndicationFeed.writeString(encoding)
864  
-
  862
+:meth:`.SyndicationFeed.writeString`
865 863
     Returns the feed as a string in the given encoding.
866 864
 
867 865
 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::
888 886
 .. _django/utils/feedgenerator.py: http://code.djangoproject.com/browser/django/trunk/django/utils/feedgenerator.py
889 887
 .. _Python datetime object: http://docs.python.org/library/datetime.html#datetime-objects
890 888
 
  889
+.. currentmodule:: django.contrib.syndication
  890
+
891 891
 Custom feed generators
892 892
 ----------------------
893 893
 
22  docs/ref/utils.txt
@@ -229,6 +229,17 @@ SyndicationFeed
229 229
 .. class:: SyndicationFeed
230 230
 
231 231
     Base class for all syndication feeds. Subclasses should provide write().
  232
+    
  233
+    .. 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])
  234
+
  235
+        Initialize the feed with the given dictionary of metadata, which applies
  236
+        to the entire feed.
  237
+        
  238
+        Any extra keyword arguments you pass to ``__init__`` will be stored in
  239
+        ``self.feed``.
  240
+
  241
+        All parameters should be Unicode objects, except ``categories``, which
  242
+        should be a sequence of Unicode objects.
232 243
 
233 244
     .. 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])
234 245
 
@@ -241,12 +252,12 @@ SyndicationFeed
241 252
     .. method:: root_attributes()
242 253
 
243 254
         Return extra attributes to place on the root (i.e. feed/channel)
244  
-        element. Called from write().
  255
+        element. Called from ``write()``.
245 256
 
246 257
     .. method:: add_root_elements(handler)
247 258
 
248 259
         Add elements in the root (i.e. feed/channel) element.
249  
-        Called from write().
  260
+        Called from ``write()``.
250 261
 
251 262
     .. method:: item_attributes(item)
252 263
 
@@ -290,6 +301,13 @@ Rss201rev2Feed
290 301
 
291 302
     Spec: http://blogs.law.harvard.edu/tech/rss
292 303
 
  304
+RssUserland091Feed
  305
+------------------
  306
+
  307
+.. class:: RssUserland091Feed(RssFeed)
  308
+
  309
+    Spec: http://backend.userland.com/rss091
  310
+
293 311
 Atom1Feed
294 312
 ---------
295 313
 

0 notes on commit 4e76f0f

Please sign in to comment.
Something went wrong with that request. Please try again.