Add docstrings to all modules, and a simple help text to the program

gahjelle · gahjelle · commit 1ed6e1aa9904 · 2018-09-17T16:53:04.000+02:00
diff --git a/reader/__main__.py b/reader/__main__.py
@@ -1,11 +1,48 @@
+"""Read the latest Real Python tutorials
+
+Usage:
+------
+
+List the latest tutorials:
+
+    $ realpython
+
+Read one tutorial:
+
+    $ realpython <id>
+
+    where <id> is the number shown when listing tutorials.
+
+Read the latest tutorial:
+
+    $ realpython 0
+
+
+Contact:
+--------
+
+- https://realpython.com/contact/
+
+More information is available at:
+
+- https://pypi.org/project/realpython-reader/
+- https://github.com/realpython/reader
+"""
+# Standard library imports
 import sys
 
+# Reader imports
 from reader import feed
 from reader import viewer
 
 
 def main() -> None:
     """Read the Real Python article feed"""
+    # Show help message
+    if "-h" in sys.argv or "--help" in sys.argv:
+        viewer.show(__doc__)
+        return
+
     # An article ID is given, show article
     if len(sys.argv) > 1:
         article = feed.get_article(sys.argv[1])
diff --git a/reader/feed.py b/reader/feed.py
@@ -1,15 +1,21 @@
+"""Interact with the Real Python feed"""
+# Standard library imports
 from typing import List
+
+# Third party imports
 import feedparser
 import html2text
-import reader
+
+# Reader imports
+from reader import URL
 
 _CACHED_FEED = feedparser.FeedParserDict()
 
 
 def _feed() -> feedparser.FeedParserDict:
     """Cache contents of the feed, so it's only read once"""
     if not _CACHED_FEED:
-        _CACHED_FEED.update(feedparser.parse(reader.URL))
+        _CACHED_FEED.update(feedparser.parse(URL))
     return _CACHED_FEED
 
 
@@ -25,7 +31,9 @@ def get_article(article_id: str) -> str:
     try:
         article = articles[int(article_id)]
     except (IndexError, ValueError):
-        raise SystemExit("Error: Unknown article ID")
+        max_id = len(articles) - 1
+        msg = f"Unknown article ID, use ID from 0 to {max_id}"
+        raise SystemExit(f"Error: {msg}")
 
     html = article.content[0].value
     text = html2text.html2text(html)
diff --git a/reader/viewer.py b/reader/viewer.py
@@ -1,3 +1,6 @@
+"""Functions for displaying the Real Python feed"""
+
+# Standard library imports
 from typing import List
 
 
