📚 DOCS: README, cli.parse: docstring, description, usage epilog, head…

…ings executablebooks#53

README.md

@@ -35,7 +35,11 @@ or
 pip install markdown-it-py
 ```
 
-## Basic usage
+## Usage
+
+### Python API Usage
+Render markdown to HTML with markdown-it-py and a custom configuration
+with and without plugins and features:
 
 ```python
 from markdown_it import MarkdownIt
@@ -66,17 +70,39 @@ tokens = md.parse(text)
 html_text = md.render(text)
 ```
 
-Also you can use it from the command-line:
+### Command-line Usage
+Render markdown to HTML with markdown-it-py from the
+command-line:
 
 ```console
-$ markdown-it
-markdown-it-py [version 0.1.0] (interactive)
-Type Ctrl-D to complete input, or Ctrl-C to exit.
->>> > **hallo** there!
-...
-<blockquote>
-<p><strong>hallo</strong> there!</p>
-</blockquote>
+usage: markdown-it [-h] [-v] [filenames [filenames ...]]
+
+Parse one or more markdown files, convert each to HTML, and print to stdout
+
+positional arguments:
+  filenames      specify an optional list of files to convert
+
+optional arguments:
+  -h, --help     show this help message and exit
+  -v, --version  show program's version number and exit
+
+Interactive:
+
+  $ markdown-it
+  markdown-it-py [version 0.0.0] (interactive)
+  Type Ctrl-D to complete input, or Ctrl-C to exit.
+  >>> # Example
+  ... > markdown *input*
+  ...
+  <h1>Example</h1>
+  <blockquote>
+  <p>markdown <em>input</em></p>
+  </blockquote>
+
+Batch:
+
+  $ markdown-it README.md README.footer.md > index.html
+
 ```
 
 ## References / Thanks

markdown_it/cli/parse.py

@@ -1,4 +1,10 @@
-from argparse import ArgumentParser
+#!/usr/bin/env python
+"""
+CLI interface to markdown-it-py
+
+Parse one or more markdown files, convert each to HTML, and print to stdout.
+"""
+import argparse
 import sys
 
 from markdown_it import __version__
@@ -59,7 +65,32 @@ def interactive(import_readline=False):
 
 def parse_args(args):
     """Parse input CLI arguments."""
-    parser = ArgumentParser()
+    parser = argparse.ArgumentParser(
+        description="Parse one or more markdown files, "
+        "convert each to HTML, and print to stdout",
+        # NOTE: Remember to update README.md w/ the output of `markdown-it -h`
+        epilog=(
+            """
+Interactive:
+
+  $ markdown-it
+  markdown-it-py [version 0.0.0] (interactive)
+  Type Ctrl-D to complete input, or Ctrl-C to exit.
+  >>> # Example
+  ... > markdown *input*
+  ...
+  <h1>Example</h1>
+  <blockquote>
+  <p>markdown <em>input</em></p>
+  </blockquote>
+
+Batch:
+
+  $ markdown-it README.md README.footer.md > index.html
+"""
+        ),
+        formatter_class=argparse.RawDescriptionHelpFormatter,
+    )
     parser.add_argument("-v", "--version", action="version", version=version_str)
     parser.add_argument(
         "filenames", nargs="*", help="specify an optional list of files to convert"