Prepare documentation

lepture · lepture · commit 6b3ed2f677db · 2019-11-02T12:11:20.000+09:00
diff --git a/.github/FUNDING.yml b/.github/FUNDING.yml
@@ -1,5 +1,6 @@
 # These are supported funding model platforms
 
+github: [lepture]
 patreon: lepture
 open_collective: # Replace with a single Open Collective username
 ko_fi: # Replace with a single Ko-fi username
diff --git a/README.md b/README.md
@@ -23,14 +23,14 @@ mistune.html(your_markdown_text)
 ## Sponsors
 
 <table>
-  <tr>
-    <td><img align="middle" width="48" src="https://user-images.githubusercontent.com/2379650/45126032-50b69880-b13f-11e8-9c2c-abd16c433495.png"></td>
-    <td>Get professionally-supported Mistune with the <a href="https://tidelift.com/subscription/pkg/pypi-mistune?utm_source=pypi-mistune&utm_medium=referral&utm_campaign=readme">Tidelift Subscription</a>.
-    </td>
-  </tr>
+<tr>
+<td><img align="middle" width="48" src="https://user-images.githubusercontent.com/2379650/45126032-50b69880-b13f-11e8-9c2c-abd16c433495.png"></td>
+<td>Get professionally-supported Mistune with the <a href="https://tidelift.com/subscription/pkg/pypi-mistune?utm_source=pypi-mistune&utm_medium=referral&utm_campaign=readme">Tidelift Subscription</a>.
+</td>
+</tr>
 </table>
 
-[**Become a backer via Patreon**](https://www.patreon.com/lepture).
+[**Support Me via GitHub Sponsors**](https://github.com/users/lepture/sponsorship).
 
 ## Installation
 
diff --git a/docs/advanced.rst b/docs/advanced.rst
@@ -0,0 +1,2 @@
+Advanced Usage of Mistune
+=========================
diff --git a/docs/api.rst b/docs/api.rst
@@ -0,0 +1,2 @@
+API Reference
+=============
diff --git a/docs/changes.rst b/docs/changes.rst
diff --git a/docs/conf.py b/docs/conf.py
@@ -38,6 +38,10 @@
 html_theme = 'sphinx_typlog_theme'
 html_theme_path = [sphinx_typlog_theme.get_path()]
 html_theme_options = {
+    'description': (
+        'A fast yet powerful Python Markdown parser '
+        'with renderers and plugins'
+    ),
     'color': '#3E7FCB',
     'github_user': 'lepture',
     'github_repo': 'mistune',
diff --git a/docs/guide.rst b/docs/guide.rst
@@ -0,0 +1,2 @@
+How to Use Mistune
+==================
diff --git a/docs/index.rst b/docs/index.rst
@@ -6,6 +6,34 @@
 Mistune: Python Markdown Parser
 ===============================
 
+Release v\ |version|.
+
+A fast yet powerful Python Markdown parser with renderers and plugins,
+compatible with sane CommonMark rules.
+
+Installation
+------------
+
+Installing Mistune is quite easy with `pip <http://www.pip-installer.org/>`_::
+
+    $ pip install mistune
+
+Mistune has no external dependencies.
+
+
+Overview
+--------
+
+
+User Guide
+----------
+
 .. toctree::
    :maxdepth: 2
-   :caption: Contents:
+
+   intro
+   guide
+   plugins
+   advanced
+   api
+   changes
diff --git a/docs/intro.rst b/docs/intro.rst
@@ -0,0 +1,12 @@
+Introduction
+============
+
+
+Extendable
+----------
+
+Sane CommonMark
+---------------
+
+Safety
+------
diff --git a/docs/plugins.rst b/docs/plugins.rst
@@ -0,0 +1,3 @@
+Mistune Markdown Plugins
+========================
+
diff --git a/mistune/__init__.py b/mistune/__init__.py
@@ -3,26 +3,55 @@
 from .inline_parser import InlineParser
 from .renderers import AstRenderer, HTMLRenderer
 from .scanner import escape, escape_url, escape_html, unikey
+from .plugins import PLUGINS
 
 
 html = Markdown(HTMLRenderer(escape=False))
 
 
-def markdown(text, escape=True, renderer=None, plugins=None):
+def create_markdown(escape=True, renderer=None, plugins=None):
+    """Create a Markdown instance based on the given condition.
+
+    :param escape: Boolean. If using html renderer, escape html.
+    :param renderer: renderer instance or string of ``html`` and ``ast``.
+    :param plugins: List of plugins, string or callable.
+
+    This method is used when you want to re-use a Markdown instance::
+
+        markdown = create_markdown(
+            escape=False,
+            renderer='html',
+            plugins=['url', 'strikethrough', 'footnote', 'table'],
+        )
+        # re-use markdown function
+        markdown('.... your text ...')
+    """
     if renderer is None or renderer == 'html':
         renderer = HTMLRenderer(escape=escape)
     elif renderer == 'ast':
         renderer = AstRenderer()
 
-    md = Markdown(renderer, plugins=plugins)
+    if plugins:
+        _plugins = []
+        for p in plugins:
+            if isinstance(p, str):
+                _plugins.append(PLUGINS[p])
+            else:
+                _plugins.append(p)
+        plugins = _plugins
+    return Markdown(renderer, plugins=plugins)
+
+
+def markdown(text, escape=True, renderer=None, plugins=None):
+    md = create_markdown(escape, renderer, plugins)
     return md(text)
 
 
 __all__ = [
     'Markdown', 'AstRenderer', 'HTMLRenderer',
     'BlockParser', 'InlineParser',
     'escape', 'escape_url', 'escape_html', 'unikey',
-    'html', 'markdown',
+    'html', 'create_markdown', 'markdown',
 ]
 
 __version__ = '2.0.0'

Original file line number	Diff line number	Diff line change
`@@ -0,0 +1,2 @@`
	`1`	`+Advanced Usage of Mistune`
	`2`	`+=========================`
Original file line number	Diff line number	Diff line change
`@@ -0,0 +1,2 @@`
	`1`	`+How to Use Mistune`
	`2`	`+==================`
Original file line number	Diff line number	Diff line change
`@@ -0,0 +1,3 @@`
	`1`	`+Mistune Markdown Plugins`
	`2`	`+========================`
	`3`	`+`