improve readme file

CHANGELOG.md

@@ -1,8 +1,8 @@
-## v1.6.2
+## v1.6.3
 
+- Add: Pagination
 - Add: Python 3 compatibility
 - Add: More test cases
-- Fix: Coverall range
 
 ## v1.6.1
 

README.md

@@ -7,6 +7,14 @@ Unofficial Python API for [Hacker News](https://news.ycombinator.com/).
 | ------------ | ------------- | ------- | -------- |
 | [![Build Status](https://travis-ci.org/karan/HackerNewsAPI.png?branch=master)](https://travis-ci.org/karan/HackerNewsAPI) | [![Coverage Status](https://coveralls.io/repos/karan/HackerNewsAPI/badge.png)](https://coveralls.io/r/karan/HackerNewsAPI) | [![Version](https://pypip.in/v/HackerNews/badge.png)](https://crate.io/packages/HackerNews/) | [![Downloads](https://pypip.in/d/HackerNews/badge.png)](https://crate.io/packages/HackerNews/) |
 
+Features
+============
+
+- Compatible with Python 2 and Python 3
+- Supports 'top', 'newest' and 'best' posts
+- Pagination
+- Handles external posts, self posts and job posts
+
 Installation
 ============
 
@@ -18,37 +26,38 @@ Installation
 
 If you love and use *HackerNewsAPI*, please consider [donating via gittip](https://www.gittip.com/Karan%20Goel/). Any support is appreciated!
 
-Classes
+Usage
 ==========
 
-## `HN`
-
-The class that parses the HN page, and builds up all stories.
-
-#### Methods
-
-`get_stories(story_type='')` - Returns a list of stories from the passed page of HN. 'story_type' can be: '' = top stories (homepage), 'newest' = most recent stories, 'best' = best stories
-
-#### Story details (keys of `dict`)
-
-* **rank** - the rank of story on the page
-* **story_id** - the story's id
-* **title** - the title of the story
-* **is_self** - true for self/job stories
-* **link** - the url it points to (None for self posts)
-* **domain** - the domain of the link (None for self posts)
-* **points** - the points/karma on the story
-* **submitter** - the user who submitted the story
-* **submitter_link** - the above user profile link
-* **published_time** - the published time ago
-* **num_comments** - the number of comments it has
-* **comments_link** - the link to the comments page
+    from hn import HN
+
+    hn = HN()
+
+    # print the first 2 pages of newest stories
+    for story in hn.get_stories(story_type='newest', page_limit=2):
+        print story["rank"], story["title"]
+        print
+
+Each `story` has the following properties
+
+- **rank** - the rank of story on the page (keep pagination in mind)
+- **story_id** - the story's id
+- **title** - the title of the story
+- **is_self** - true for self/job stories
+- **link** - the url it points to (`''` for self posts)
+- **domain** - the domain of the link (`''` for self posts)
+- **points** - the points/karma on the story
+- **submitter** - the user who submitted the story (`''` for job posts)
+- **submitter_profile** - the above user's profile link (can be `''`)
+- **published_time** - the published time
+- **num_comments** - the number of comments a story has
+- **comments_link** - the link to the comments page
 
 Example
 ========
 
 See [`test_bot.py`](https://github.com/karan/HackerNewsAPI/blob/master/test_bot.py)
-        
+
 Contribute
 ========