Incorrect docs for args to SyndicationFeed.add_item

[slinkp@…]

The docs at ​http://docs.djangoproject.com/en/1.2/ref/contrib/syndication/#syndicationfeed-classes
say that SyndicationFeed.add_item takes only keyword args.
In fact as per ​http://docs.djangoproject.com/en/dev/ref/utils/#syndicationfeed there are three positional args followed by keyword args:

    def add_item(self, 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):

If you try to pass those first three as kwargs it blows up with a TypeError.

[Russell Keith-Magee]

I can't work out what you're reporting here. There are three required arguments, and a series of optional arguments. You need to specify all of the required arguments, and all usual Python argument semantics apply. I can't see anything confusing in the existing text.

[slinkp@…]

Sorry, I may have confused things a bit by linking to both 1.2 and dev docs, my mistake.
I was trying to say that the args are documented in two places in the docs, and they disagree.

​http://docs.djangoproject.com/en/dev/ref/utils/#syndicationfeed is correct.

​http://docs.djangoproject.com/en/dev/ref/contrib/syndication/#syndicationfeed-classes is wrong, it says:

SyndicationFeed.add_item(**kwargs)

    Add an item to the feed with the given parameters.

    Required keyword arguments are:

        * title
        * link
        * description

That should be replaced by:

SyndicationFeed.add_item(title, link, description, **kwargs)

    Add an item to the feed with the given parameters.

[Gabriel Hurley]

Agreed that the two are inconsistent. Particularly it's /ref/contrib/syndication/ that needs to be fixed. The first three arguments there are positional arguments, not keyword arguments, and it's worth enumerating the arguments as in the other doc linked.

Moreover, the crossref targets for those docs are a total disaster. Neither django.contrib.syndication.django.utils.feedgenerator.SyndicationFeed nor django.contrib.syndication.SyndicationFeed exist. That whole section needs to be fixed up.

[Gabriel Hurley]

In [15739]:

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.

[Gabriel Hurley]

In [15740]:

[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.