Opened 4 years ago

Closed 4 years ago

Last modified 4 years ago

#15504 closed (fixed)

Incorrect docs for args to SyndicationFeed.add_item

Reported by: slinkp@… Owned by: nobody
Component: Documentation Version: 1.2
Severity: Keywords:
Cc: Triage Stage: Accepted
Has patch: no Needs documentation: no
Needs tests: no Patch needs improvement: no
Easy pickings: UI/UX:

Description

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.

Change History (5)

comment:1 Changed 4 years ago by russellm

  • Needs documentation unset
  • Needs tests unset
  • Patch needs improvement unset
  • Resolution set to invalid
  • Status changed from new to closed

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.

comment:2 Changed 4 years ago by slinkp@…

  • Component changed from Uncategorized to Documentation
  • Resolution invalid deleted
  • Status changed from closed to reopened

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.

comment:3 Changed 4 years ago by gabrielhurley

  • Triage Stage changed from Unreviewed to Accepted

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.

comment:4 Changed 4 years ago by gabrielhurley

  • Resolution set to fixed
  • Status changed from reopened to closed

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.

comment:5 Changed 4 years ago by gabrielhurley

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.

Note: See TracTickets for help on using tickets.
Back to Top