From cc3405c29c975bc4a056fde274df6d08e58e43e4 Mon Sep 17 00:00:00 2001
From: Waylan Limberg <waylan.limberg@icloud.com>
Date: Fri, 1 Aug 2014 21:43:53 -0400
Subject: Updated extension API docs for Extension.__init__ refactor

Relates to #325.
---
 docs/extensions/api.txt | 27 ++++++++++++++++++---------
 1 file changed, 18 insertions(+), 9 deletions(-)

(limited to 'docs')

diff --git a/docs/extensions/api.txt b/docs/extensions/api.txt
index 715df6d..d11c534 100644
--- a/docs/extensions/api.txt
+++ b/docs/extensions/api.txt
@@ -550,10 +550,13 @@ If an extension uses any parameters that the user may want to change,
 those parameters should be stored in ``self.config`` of your 
 ``markdown.Extension`` class in the following format:
 
-    self.config = {parameter_1_name : [value1, description1],
-                   parameter_2_name : [value2, description2] }
+    class MyExtension(markdown.extensions.Extension):
+    	def __init__(self, *args, **kwargs):
+    		self.config = {parameter_1_name : [value1, description1],
+                           parameter_2_name : [value2, description2] }
+            super(MyExtension, self).__init__(*args, **kwargs)
 
-When stored this way the config parameters can be over-ridden from the
+When implemented this way the config parameters can be over-ridden from the
 command line or at the time Markdown is initiated:
 
     markdown.py -x myextension(SOME_PARAM=2) inputfile.txt > output.txt
@@ -573,8 +576,7 @@ For example:
 
     import markdown
     import myextension
-    configs = {...}
-    myext = myextension.MyExtension(configs=configs)
+    myext = myextension.MyExtension(option='value')
     md = markdown.Markdown(extensions=[myext])
 
 This is especially useful if you need to implement a large number of extensions 
@@ -583,14 +585,21 @@ with more than one residing in a module.
 However, for historical reasons, Markdown also accepts "named" third party 
 extensions. In that case, only one extension can be defined per module
 and that extension must define a module-level function called 
-`makeExtension` that takes an optional parameter consisting of a dictionary 
-of configuration over-rides and returns an instance of the extension.  For example:
+`makeExtension` that takes `*args` and `**kwargs`.  For example:
 
     class MyExtension(markdown.extensions.Extension)
         # Define extension here...
 
-    def makeExtension(configs=None):
-        return MyExtension(configs=configs)
+    def makeExtension(*args, **kwargs):
+        return MyExtension(*args, **kwargs)
+
+!!! warning
+    Previous versions of Python-Markdown expected a `config` keyword which contained
+    a dictionary (or list of tuples) of options. To maintain backward compatability,
+    the `config` keyword is given special treatment and you should avoid using "config"
+    as an option name. Additionaly, in some past situations, the `config` dict may have
+    been passed in as a positional argument. Therefore, it is sugegsted that positional
+    arguments be avoided for any othe purpose.
 
 When Markdown is passed the "name" of your extension as a string, it will import 
 the module and call the `makeExtension` function to initiate your extension.
-- 
cgit v1.2.3