Convert doc to napoleon style

feedpipe.py

@@ -8,70 +8,83 @@
 
 # TODO: document entry objects better (or better yet, make Steve do it.)
 class FeedPipe(object):
-    """
-    FeedPipe is a handy tool to mutate feeds.  Think if it as your very own
-    Yahoo Pipes.
-    [It was originally written in Perl](https://metacpan.org/pod/Feed::Pipe) by
-    [Vince Veselosky](http://www.control-escape.com/), and ported to Python by
-    [Arthur Axel fREW Schmidt](https://blog.afoolishmanifesto.com) for use on
+    """ FeedPipe is a tool to mutate feeds; it's your very own Yahoo Pipes.
+
+    `It was originally written in Perl <https://metacpan.org/pod/Feed::Pipe>`_ by
+    `Vince Veselosky <http://www.control-escape.com/>`_, and ported to Python by
+    `Arthur Axel fREW Schmidt <https://blog.afoolishmanifesto.com>`_ for use on
     AWS Lambda.
 
-    # Example usage:
+    Args:
+        title (str): title of feed; defaults to "Combined Feed"
+
+        id (str): id of feed; defaults to autogenerated uuid
+
+        updated (str of iso8601 datetime): last time feed was updated; defaults to current time
+
+    Example::
 
         import FeedPipe from feedpipe;
-        fp = FeedPipe(title => "Mah Bukkit") \
-            .cat('1.xml', '2.rss', '3.atom') \
-            .grep(lambda e: 'lolrus' in e.title.text) \
-            .sort \
+        fp = FeedPipe(title => "Mah Bukkit") \\
+            .cat('1.xml', '2.rss', '3.atom') \\
+            .grep(lambda e: 'lolrus' in e.title.text) \\
+            .sort \\
             .head
 
-        print(fp.as_xml)
+        print(fp.as_xml())
 
-    # Entry Objects:
+    .. _entry:
 
-    A few of the most important methods in FeedPipe use "entry" objects.  Entry
-    objects are [sorta documented](http://home.blarg.net/~steveha/pyfeed.html),
-    but not really.  Basically they have the following properties:
+        A few of the most important methods in FeedPipe use entry_ objects.
+        Entry objects are `sorta documented
+        <http://home.blarg.net/~steveha/pyfeed.html>`_,
+        but not really.  Basically they have the following properties:
 
-        * id
-        * title
-        * updated
-        * content
-        * link
-        * summary
-        * published
+            * id
+            * title
+            * updated
+            * content
+            * link
+            * summary
+            * published
 
     """
     def __init__(self,
                  title="Combined Feed",
-                 id='urn:' + str(uuid4()),
-                 updated=datetime.now().isoformat()):
-        """
-        Returns a new FeedPipe instance.
-
-            fp = FeedPipe(title="Station")
-
-        Arguments:
-            title -- title of feed; defaults to "Combined Feed"
-            id -- id of feed; defaults to autogenerated uuid
-            updated -- last time feed was updated; defaults to current time
-        """
+                 id=None,
+                 updated=None):
         self.title = title
+
+        if id is None:
+            id = 'urn:' + str(uuid4())
         self.id = id
+
+        if updated is None:
+            updated = datetime.now().isoformat()
         self.updated = updated
+
         self.entries = []
 
     # TODO: this should be lazily pulled?
     def cat(self, feeds):
-        """
-        Adds new entries to the FeedPipe.  Returns self for chaining.
+        """Adds list of new entry_ objects to the FeedPipe
+
+        .. _feed:
+
+            * Filenames start with . or / (`/foo/bar/baz`, or `./foo`)
+            * URLs start with http:// or https://
+            * Preparsed Data Strucutres will have type() of foo
+            * Everything else is assumed to be a string containing XML
+
+        Example::
 
             fp.cat(['https://blog.afoolishmanifesto.com/index.xml'])
 
-        Arguments:
-            feeds -- an array of feeds; can be a string, URL, file location, or
-                     preparsed feedparser data structure
+        Args:
+            feeds (List[feed_]): an array of feeds
 
+        Returns:
+            self: you know, for chaining!
         """
         # TODO: *actually* make this handle all the stuff documented above
         for feed in feeds:
@@ -119,57 +132,68 @@ def cat(self, feeds):
         return self
 
     def grep(self, filter):
-        """
-        Filters the entries in the FeedPipe.  Returns self for chaining.
+        """ Filters the entries in the FeedPipe
+
+        Example::
+
+            fp.grep(lambda e: "Video" not in e.title.text)
 
-            fp.grep(lambda e: "Video" not in e.title)
+        Args:
+            filter (callback): callback takes an entry; return value is True if
+            entry should be included.
 
-        Arguments:
-            filter -- a callback that takes an entry; return value is if entry
-                      should be included.
+        Returns:
+            self: for chaining
         """
         self.entries = [x for x in self.entries if filter(x)]
 
         return self
 
     def head(self, length=10):
-        """
-        Truncates feed starting at the beginning.  Returns self for chaining.
+        """ Truncates feed starting at the beginning
+
+        Example::
 
             fp.head()
 
-        Arguments:
-            length -- how many entries to include; defaults to 10
+        Args:
+            length (int): how many entries to include; defaults to 10
+
+        Returns:
+            self: for chaining
         """
         self.entries = self.entries[:length]
 
         return self
 
     def map(self, transform):
-        """
-        Transforms entries in the FeedPipe.  Returns self for chaining.
+        """ Transforms entries in the FeedPipe
+
+        Example::
 
             def fix_title(e):
                 e.title = "[STATION] " + e.title.text
                 return e
 
             fp.map(fix_title)
 
-        Arguments:
-            transform -- a callback that takes an entry and returns it,
-                         possibly modified
+        Args:
+            transform (callback): callback takes entry_ and returns it,
+            possibly modified
         """
         self.entries = [transform(x) for x in self.entries]
 
         return self
 
     def reverse(self):
-        """
-        Reverses the entries in the FeedPipe.  Returns self for chaining.
+        """ Reverses the entries in the FeedPipe
+
+        Example::
 
             fp.reverse()
 
-        Does no harm; takes no arguments.
+        Returns:
+            self: for chaining
         """
         self.entries.reverse()
 
@@ -182,15 +206,16 @@ def _default_key(e):
             return e.published.text
 
     def sort(self, cmp=None, key=_default_key, reverse=True):
-        """
-        Sorts the entries in the FeedPipe.  Returns self for chaining.
+        """ Sorts the entries in the FeedPipe
+
+        Example::
 
-            fp.sort(key='title')
+            fp.sort(key=lambda e: e.title.text)
 
-        Arguments:
-            cmp, key, and reverse; matches the interface of [the sorter
-            builtin](https://docs.python.org/2/library/functions.html#sorted).
-            key defaults to updated/published and reverse defaults to True, so
+        Args:
+            cmp, key, and reverse; matches the interface of `the sorter
+            builtin <https://docs.python.org/2/library/functions.html#sorted>`_.
+            ``key`` defaults to updated/published and ``reverse`` defaults to True, so
             that the default sort is newest at the beginning.
         """
 
@@ -199,28 +224,33 @@ def sort(self, cmp=None, key=_default_key, reverse=True):
         return self
 
     def tail(self, length=10):
-        """
-        Truncates the feed from the end.  Returns self for chaining.
+        """ Truncates the FeedPipe from the end
+
+
+        Example::
 
             fp.tail()
 
-        Arguments:
-            length -- how many entries to include, starting at the end.
-                      Defaults to 10.
+        Args:
+            length (int): how many entries to include, starting at the end.
+            Defaults to 10.
+
+        Returns:
+            self: for chaining
         """
         self.entries = self.entries[len(self.entries) - length:]
 
         return self
 
     def as_atom_obj(self):
-        """
-        Returns a new
-        [pyfeed.feed.atom.Feed](http://home.blarg.net/~steveha/pyfeed.html)
-        object.
+        """ Object for interacting with XML directly
+
+        Example::
 
             fp.as_atom_obj()
 
-        No arguments.
+        Returns:
+            `feed.atom.Feed <http://home.blarg.net/~steveha/pyfeed.html>`_.
         """
         feed = FA.Feed()
         feed.generator = 'feedpipe 0.0.1'
@@ -239,12 +269,14 @@ def as_atom_obj(self):
         return feed
 
     def as_xml(self):
-        """
-        Returns a string containing the XML of the feed.
+        """ Gets the actual XML
+
+        Example::
 
             fp.as_xml()
 
-        Arguments: none
+        Returns:
+            feed: XML encoded in string
         """
         xmldoc = FA.XMLDoc()
         xmldoc.root_element = self.as_atom_obj()
@@ -253,10 +285,12 @@ def as_xml(self):
 
     def count(self):
         """
-        Returns the count of the entries in the FeedPipe.
+
+        Example::
 
             fp.count()
 
-        Takes no arguments.
+        Returns:
+            int: count of entries in the FeedPipe
         """
         return len(self.entries)