Mark special treatment of extension names as PendingDeprecation

The builtin extensions will no longer get special treatment and have
the path ("markdown.extensions.") appended . The same applies for
"mdx_" extensions. All names extension must provide the full path.
Fixes #336.

Also deprecating support for passing in extension config settings
as part of the string name. The extension_configs keyword should
be used instead. Fixes #335.

Also raising PendingDeprecationWarnings for positional args or the
"config" keyword on the Extension Class. Pass each setting as a
seperate keyword instead.

Docs and tests are updated. Still need to update extension API docs.

3 files changed, 55 insertions, 27 deletions

diff --git a/docs/cli.txt b/docs/cli.txt
index acad4ff..7741d34 100644
--- a/docs/cli.txt
+++ b/docs/cli.txt
@@ -147,17 +147,14 @@ The `--extension_configs` option will only support YAML config files if [PyYaml]
 installed on your system. JSON should work with no additional dependencies. The format
 of your config file is automatically detected.
 
-As an alternative, you may append the extension configs as a string to the extension name 
-that is provided to the `-x-` option in the following format:
-
-	$ python -m markdown -x "markdown.extensions.footnotes(PLACE_MARKER=~~~~~~~~,UNIQUE_IDS=1)" input.txt
-
-Note that there are no quotes or whitespace in the above format, which severely limits 
-how it can be used. For more complex settings, it is suggested that the 
-`--extension_configs` option be used.
+!!!warning
+	The previously documented method of appending the extension configs as a string to the 
+	extension name will be deprecated in Python-Markdown version 2.6. The `--extension_configs` 
+	option should be used instead. See the [2.5 release notes] for more information.
 
 [ec]: reference.html#extension_configs
 [YAML]: http://yaml.org/
 [JSON]: http://json.org/
 [PyYAML]: http://pyyaml.org/
+[2.5 release notes]: release-2.5.txt
 
diff --git a/docs/reference.txt b/docs/reference.txt
index 033b658..afc3b05 100644
--- a/docs/reference.txt
+++ b/docs/reference.txt
@@ -66,11 +66,12 @@ The following options are available on the `markdown.markdown` function:
     The list of extensions may contain instances of extensions and/or strings 
     of extension names. 
 
-        extensions=[MyExtension(), 'path.to.my.ext', 'extra']
+        extensions=[MyExtension(), 'path.to.my.ext']
     
     !!! warning
-        The prefered method is to pass in an instance of an extension. The other
-        methods may be removed in a future version of Python-Markdown.
+        The prefered method is to pass in an instance of an extension. Strings
+		should only be used when it is impossable to import the Extension Class
+		directly (from the command line or in a template).
     
     When passing in extension instances, each class instance must be a subclass
     of `markdown.extensions.Extension` and any configuration options should be 
@@ -86,24 +87,27 @@ The following options are available on the `markdown.markdown` function:
     If an extension name is provided as a string, the extension must be 
     importable as a python module on your PYTHONPATH. Python's dot notation is 
     supported. Therefore, to import the 'extra' extension, one could do 
-    `extensions=['markdown.extensions.extra']` However, if no dots are provided 
-    in the string (`extensions=['extra']`) Markdown will first look for the 
-    module `markdown.extensions.extra` (the built-in extension), then a module 
-    named `mdx_extra` ('mdx_' will be appended to the beginning of the string) 
-    at the root of your PYTHONPATH. 
+    `extensions=['markdown.extensions.extra']`  
 
-    When loading an extension by name (as a string), you may either pass in
-    configuration settings to the extension using the 
-    [extension_configs](#extension_configs) keyword or by appending the 
-    settings to the name in the following format:
+	Additionaly, a Class may be specified in the name. The class must be at the end of 
+	the name and be seperated by a colon from the module. 
 
-        extensions=['name(option1=value,option2=value)']
-    
-    Note that there are no quotes or whitespace in the above format, which 
-    severely limits how it can be used. For more complex settings, it is 
-    suggested that an instance of a class be passed in or, if that's not 
-    possible, the [extension_configs](#extension_configs) keyword
-    be used.
+	Therefore, if you were to import the class like this:
+	
+		from path.to.module import SomeExtensionClass
+
+	Then the named extension would comprise this string:
+
+		"path.to.module:SomeExtensionClass"
+
+	!!! note
+	You should only need to specify the class name if more than one extension is defined
+	within the same module. The extensions that come with Python-Markdown do *not*
+	need to have the class name specified.
+
+    When loading an extension by name (as a string), you may pass in
+    configuration settings to the extension using the 
+    [extension_configs](#extension_configs) keyword.
 
     !!! seealso "See Also"
         See the documentation of the [Extension API](extensions/api.html) for 
diff --git a/docs/release-2.5.txt b/docs/release-2.5.txt
index a81acfd..d45fe24 100644
--- a/docs/release-2.5.txt
+++ b/docs/release-2.5.txt
@@ -31,6 +31,33 @@ Backwards-incompatible Changes
 [CodeHilite Extension]: extensions/code_hilite.html
 [linenumes]: extensions/code_hilite.html#usage
 
+* In previous versions of Python-Markdown, the builtin extensions received
+  special status and did not require the full path to be provided. Additionaly,  
+  third party extensions whose name started with "mdx_" received the same 
+  special treatment. This behavior will be deprecated in version 2.6 and will
+  raise a PendingDeprecationWarning in 2.5. Ensure that you always use the full 
+  path to your extensions. For example, if you previously did the following:
+
+       markdown.markdown(text, extensions=['extra'])
+
+  You should change your code to the following:
+
+	   markdown.markdown(text, extensions=['markdown.extensions.extra'])
+
+  The same applies to the command line:
+
+       $ python -m markdown -x markdown.extensions.extra input.txt
+
+  See the [documentation](reference.html#extensions) for a full explaination
+  of the current behavior.
+
+* The previously documented method of appending the extension configs as 
+  a string to the extension name will be deprecated in Python-Markdown 
+  version 2.6 and will raise a PendingDeprecationWarning in 2.5. The 
+  [extension_configs](reference.html#extension_configs) keyword should 
+  be used instead. See the [documentation](reference.html#extension-configs) 
+  for a full explaination of the current behavior.
+
 What's New in Python-Markdown 2.5
 ---------------------------------