From ce45beb37f33543817faa91242028c9a90ae5960 Mon Sep 17 00:00:00 2001 From: Lars Kiesow Date: Sat, 4 May 2013 20:08:08 +0200 Subject: [PATCH] Documentation fixes --- feedgenerator/__init__.py | 6 +++--- feedgenerator/entry.py | 6 ++++++ feedgenerator/feed.py | 12 +++++++++--- feedgenerator/podcast.py | 2 ++ feedgenerator/podcast_entry.py | 6 ++++-- readme.md | 19 ++++++++++--------- 6 files changed, 34 insertions(+), 17 deletions(-) diff --git a/feedgenerator/__init__.py b/feedgenerator/__init__.py index a7c0af2..db9edca 100644 --- a/feedgenerator/__init__.py +++ b/feedgenerator/__init__.py @@ -33,9 +33,9 @@ Note that for the methods which set fields that can occur more than once in a feed you can use all of the following ways to provide data: - - Provide the data for that element as keyword arguments:: - - Provide the data for that element as dictionary:: - - Provide a list of dictionaries with the data for several elements:: + - Provide the data for that element as keyword arguments + - Provide the data for that element as dictionary + - Provide a list of dictionaries with the data for several elements Example:: diff --git a/feedgenerator/entry.py b/feedgenerator/entry.py index 8aef945..bc6879d 100644 --- a/feedgenerator/entry.py +++ b/feedgenerator/entry.py @@ -17,6 +17,9 @@ from feedgenerator.util import ensure_format class FeedEntry(object): + '''FeedEntry call representing an ATOM feeds entry node or an RSS feeds item + node. + ''' # ATOM # required @@ -323,9 +326,11 @@ class FeedEntry(object): - a list of dictionaries containing the link fields A link has the following fields: + - *href* is the URI of the referenced resource (typically a Web page) - *rel* contains a single link relationship type. It can be a full URI, or one of the following predefined values (default=alternate): + - *alternate* an alternate representation of the entry or feed, for example a permalink to the html version of the entry, or the front page of the weblog. @@ -335,6 +340,7 @@ class FeedEntry(object): - *related* an document related to the entry or feed. - *self* the feed itself. - *via* the source of the information provided in the entry. + - *type* indicates the media type of the resource. - *hreflang* indicates the language of the referenced resource. - *title* human readable information about the link, typically for diff --git a/feedgenerator/feed.py b/feedgenerator/feed.py index 0358fba..88ecef5 100644 --- a/feedgenerator/feed.py +++ b/feedgenerator/feed.py @@ -1,12 +1,13 @@ #!/bin/env python # -*- coding: utf-8 -*- ''' - feedgenerator - ~~~~~~~~~~~~~ + feedgenerator.feed + ~~~~~~~~~~~~~~~~~~ :copyright: 2013, Lars Kiesow :license: FreeBSD and LGPL, see license.* for more details. + ''' from lxml import etree @@ -18,6 +19,8 @@ from feedgenerator.util import ensure_format class FeedGenerator(object): + '''FeedGenerator for generating ATOM and RSS feeds. + ''' __feed_entries = [] @@ -459,9 +462,11 @@ class FeedGenerator(object): - a list of dictionaries containing the link fields A link has the following fields: + - *href* is the URI of the referenced resource (typically a Web page) - *rel* contains a single link relationship type. It can be a full URI, or one of the following predefined values (default=alternate): + - *alternate* an alternate representation of the entry or feed, for example a permalink to the html version of the entry, or the front page of the weblog. @@ -471,6 +476,7 @@ class FeedGenerator(object): - *related* an document related to the entry or feed. - *self* the feed itself. - *via* the source of the information provided in the entry. + - *type* indicates the media type of the resource. - *hreflang* indicates the language of the referenced resource. - *title* human readable information about the link, typically for @@ -744,7 +750,7 @@ class FeedGenerator(object): The value should be an IETF language tag. :param language: Language of the feed. - :: Language of the feed. + :returns: Language of the feed. ''' if not language is None: self.__rss_language = language diff --git a/feedgenerator/podcast.py b/feedgenerator/podcast.py index 0fdfa7f..d4ab31a 100644 --- a/feedgenerator/podcast.py +++ b/feedgenerator/podcast.py @@ -21,6 +21,8 @@ from feedgenerator.util import ensure_format class PodcastGenerator(FeedGenerator): + '''FeedGenerator extension for podcasts. + ''' ## ITunes tags diff --git a/feedgenerator/podcast_entry.py b/feedgenerator/podcast_entry.py index 6215cb3..3782d0e 100644 --- a/feedgenerator/podcast_entry.py +++ b/feedgenerator/podcast_entry.py @@ -1,8 +1,8 @@ #!/bin/env python # -*- coding: utf-8 -*- ''' - feedgenerator.podcast - ~~~~~~~~~~~~~~~~~~~~~ + feedgenerator.podcast_entry + ~~~~~~~~~~~~~~~~~~~~~~~~~~~ Extends the feedgenerator to produce podcasts. @@ -20,6 +20,8 @@ from feedgenerator.util import ensure_format class PodcastEntry(FeedEntry): + '''FeedEntry extension for podcasts. + ''' ## ITunes tags diff --git a/readme.md b/readme.md index ca29909..5b0830e 100644 --- a/readme.md +++ b/readme.md @@ -1,20 +1,21 @@ ============= -feedgenerator +Feedgenerator ============= This module can be used to generate web feeds in both ATOM and RSS format. The included PodcastGenerator furthermore includes all of Apples RSS extension for Podcasts. -- copyright: 2013 by Lars Kiesow -- license: FreeBSD and LGPL, see license.bsd or license.lgpl for more details. +It is licensed under the terms of both, the FreeBSD license and the LGPL. +Choose the one which is more convenient for you. For more details have a look +at license.bsd and license.lgpl. ------------- Create a Feed ------------- -To create a feed simply instanciate the FeedGenerator class and insert some +To create a feed simply instantiate the FeedGenerator class and insert some data:: >>> from feedgenerator.feed import FeedGenerator @@ -31,9 +32,9 @@ data:: Note that for the methods which set fields that can occur more than once in a feed you can use all of the following ways to provide data: -- Provide the data for that element as keyword arguments:: -- Provide the data for that element as dictionary:: -- Provide a list of dictionaries with the data for several elements:: +- Provide the data for that element as keyword arguments +- Provide the data for that element as dictionary +- Provide a list of dictionaries with the data for several elements Example:: @@ -67,7 +68,7 @@ instantiation of the FeedEntry object:: >>> fe.title('The First Episode') The FeedGenerators method add_entry(...) without argument provides will -automaticall generate a new FeedEntry object, append it to the feeds +automatically generate a new FeedEntry object, append it to the feeds internal list of entries and return it, so that additional data can be added. @@ -91,7 +92,7 @@ For the episodes of the podcast you should also use PodcastEntry instead of FeedEntry. However, if you use the add_entry(...) method to generator the entry objects, it will take care of that for you. -Of cause you can still produce a normat ATOM or RSS feed, even if you use +Of cause you can still produce a normal ATOM or RSS feed, even if you use the PodcastGenerator using the {atom,rss}_{str,file} methods. ---------------------