📚 DOCS: Improve documentation for CLI

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"