From 2899c3749edcad4baab0edfb5402fd4f40e75361 Mon Sep 17 00:00:00 2001
From: Wes Turner <wes@wrd.nu>
Date: Thu, 1 Oct 2020 11:01:51 -0400
Subject: [PATCH] :books: DOCS: README, cli.parse: docstring, description,
 usage epilog, headings #53

---
 README.md                | 46 +++++++++++++++++++++++++++++++---------
 markdown_it/cli/parse.py | 35 ++++++++++++++++++++++++++++--
 2 files changed, 69 insertions(+), 12 deletions(-)

diff --git a/README.md b/README.md
index 5a79e3de..417e3266 100644
--- a/README.md
+++ b/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
diff --git a/markdown_it/cli/parse.py b/markdown_it/cli/parse.py
index ac8ccddd..32374d31 100644
--- a/markdown_it/cli/parse.py
+++ b/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"