aboutsummaryrefslogtreecommitdiffstats
path: root/docs
diff options
context:
space:
mode:
Diffstat (limited to 'docs')
-rw-r--r--docs/cli.txt13
-rw-r--r--docs/reference.txt42
-rw-r--r--docs/release-2.5.txt27
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
---------------------------------