Update docs for cli and renderers

docs/advanced.rst

@@ -1,93 +1,6 @@
 Advanced Guide
 ==============
 
-.. _renderers:
-
-Use renderers
--------------
-
-You can customize HTML output with your own renderers. Create a subclass
-of ``mistune.HTMLRenderer``::
-
-
-    class MyRenderer(mistune.HTMLRenderer):
-        def codespan(self, text):
-            if text.startswith('$') and text.endswith('$'):
-                return '<span class="math">' + escape(text) + '</span>'
-            return '<code>' + escape(text) + '</code>'
-
-    # use customized renderer
-    markdown = mistune.create_markdown(renderer=MyRenderer())
-    print(markdown('hi `$a^2=4$`'))
-
-Here is a a list of available renderer functions::
-
-    # inline level
-    text(self, text)
-    link(self, text, url, title=None)
-    image(self, alt, url, title=None)
-    emphasis(self, text)
-    strong(self, text)
-    codespan(self, text)
-    linebreak(self)
-    softbreak(self)
-    inline_html(self, html)
-
-    # block level
-    paragraph(self, text)
-    heading(self, text, level, **attrs)
-    blank_line(self)
-    thematic_break(self)
-    block_text(self, text)
-    block_code(self, code, info=None)
-    block_quote(self, text)
-    block_html(self, html)
-    block_error(self, html)
-    list(self, text, ordered, **attrs)
-    list_item(self, text, **attrs)
-
-    # provided by strikethrough plugin
-    strikethrough(self, text)
-
-    # provided by mark plugin
-    mark(self, text)
-
-    # provided by insert plugin
-    insert(self, text)
-
-    # provided by subscript plugin
-    subscript(self, text)
-
-    # provided by abbr plugin
-    abbr(self, text, title)
-
-    # provided by ruby plugin
-    ruby(self, text, rt)
-
-    # provided by task_lists plugin
-    task_list_item(self, text, checked=False, **attrs)
-
-    # provide by table plugin
-    table(self, text)
-    table_head(self, text)
-    table_body(self, text)
-    table_row(self, text)
-    table_cell(self, text, align=None, head=False)
-
-    # provided by footnotes plugin
-    footnote_ref(self, key, index)
-    footnotes(self, text)
-    footnote_item(self, text, key, index)
-
-    # provide by def_list plugin
-    def_list(self, text)
-    def_list_head(self, text)
-    def_list_item(self, text)
-
-    # provide by math plugin
-    block_math(self, text)
-    inline_math(self, text)
-
 
 Create plugins
 --------------

docs/cli.rst

@@ -3,17 +3,69 @@ Command line tools
 
 .. meta::
     :description: How to use the command line tools of Mistune
-        to convert Markdown to HTML.
+        to convert Markdown to HTML, RST, and etc.
 
-A command line tool to convert markdown content into HTML, here
-are some use cases of the command line tool::
+A command line tool to convert markdown content into HTML, learn
+about the options of the command line tool::
 
-    $ python -m mistune -m "Hi **Markdown**"
-    <p>Hi <strong>Markdown</strong></p>
+    $ python -m mistune -h
+
+    Mistune, a sane and fast python markdown parser.
+
+    Here are some use cases of the command line tool:
+
+        $ python -m mistune -m "Hi **Markdown**"
+        <p>Hi <strong>Markdown</strong></p>
+
+        $ python -m mistune -f README.md
+        <p>...
+
+        $ cat README.md | python -m mistune
+        <p>...
+
+    optional arguments:
+      -h, --help            show this help message and exit
+      -m MESSAGE, --message MESSAGE
+                            the markdown message to convert
+      -f FILE, --file FILE  the markdown file to convert
+      -p NAME [NAME ...], --plugin NAME [NAME ...]
+                            specifiy a plugin to use
+      --escape              turn on escape option
+      --hardwrap            turn on hardwrap option
+      -o OUTPUT, --output OUTPUT
+                            write the rendered result into file
+      -r RENDERER, --renderer RENDERER
+                            specify the output renderer
+      --version             show program's version number and exit
+
+Convert Markdown to HTML
+------------------------
+
+By default, the command line tool of mistune will convert markdown text
+to HTML text::
 
     $ python -m mistune -f README.md
-    <p>...
 
-Learn more about the options::
+Convert Markdown to RestructuredText
+------------------------------------
 
-    $ python -m mistune -h
+Mistune has a built-in RestructuredText formatter, specify the renderer
+with ``-r rst``::
+
+    $ python -m mistune -f README.md -r rst
+
+Reformat Markdown
+-----------------
+
+You can reformat the markdown file with a markdown renderer::
+
+    $ python -m mistune -f README.md -r markdown -o README.md
+
+This command will reformat the text in ``README.md``.
+
+Unix PIPE
+---------
+
+The command line tool supports unix PIPE. For instance::
+
+    $ echo "foo **bar**" | python -m mistune

docs/index.rst

@@ -36,6 +36,7 @@ User Guide
 
    guide
    cli
+   renderers
    plugins
    directives
    advanced

docs/renderers.rst

@@ -0,0 +1,96 @@
+Renderers
+=========
+
+
+Customize HTMLRenderer
+----------------------
+
+You can customize HTML output with your own renderers. Create a subclass
+of ``mistune.HTMLRenderer``::
+
+
+    class MyRenderer(mistune.HTMLRenderer):
+        def codespan(self, text):
+            if text.startswith('$') and text.endswith('$'):
+                return '<span class="math">' + escape(text) + '</span>'
+            return '<code>' + escape(text) + '</code>'
+
+    # use customized renderer
+    markdown = mistune.create_markdown(renderer=MyRenderer())
+    print(markdown('hi `$a^2=4$`'))
+
+Here is a a list of available renderer functions::
+
+    # inline level
+    text(self, text)
+    link(self, text, url, title=None)
+    image(self, alt, url, title=None)
+    emphasis(self, text)
+    strong(self, text)
+    codespan(self, text)
+    linebreak(self)
+    softbreak(self)
+    inline_html(self, html)
+
+    # block level
+    paragraph(self, text)
+    heading(self, text, level, **attrs)
+    blank_line(self)
+    thematic_break(self)
+    block_text(self, text)
+    block_code(self, code, info=None)
+    block_quote(self, text)
+    block_html(self, html)
+    block_error(self, html)
+    list(self, text, ordered, **attrs)
+    list_item(self, text, **attrs)
+
+    # provided by strikethrough plugin
+    strikethrough(self, text)
+
+    # provided by mark plugin
+    mark(self, text)
+
+    # provided by insert plugin
+    insert(self, text)
+
+    # provided by subscript plugin
+    subscript(self, text)
+
+    # provided by abbr plugin
+    abbr(self, text, title)
+
+    # provided by ruby plugin
+    ruby(self, text, rt)
+
+    # provided by task_lists plugin
+    task_list_item(self, text, checked=False, **attrs)
+
+    # provide by table plugin
+    table(self, text)
+    table_head(self, text)
+    table_body(self, text)
+    table_row(self, text)
+    table_cell(self, text, align=None, head=False)
+
+    # provided by footnotes plugin
+    footnote_ref(self, key, index)
+    footnotes(self, text)
+    footnote_item(self, text, key, index)
+
+    # provide by def_list plugin
+    def_list(self, text)
+    def_list_head(self, text)
+    def_list_item(self, text)
+
+    # provide by math plugin
+    block_math(self, text)
+    inline_math(self, text)
+
+
+RestructuredText Renderer
+-------------------------
+
+
+Markdown Renderer
+-----------------