diff options
Diffstat (limited to 'docs')
| -rw-r--r-- | docs/cli.txt | 13 | ||||
| -rw-r--r-- | docs/reference.txt | 42 | ||||
| -rw-r--r-- | docs/release-2.5.txt | 27 |
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 --------------------------------- |