From bf4a2c69349320666b39d049bf7cef782334b9b4 Mon Sep 17 00:00:00 2001 From: Waylan Limberg Date: Fri, 1 Aug 2014 21:12:31 -0400 Subject: Update reference docs for recent Extension.__init__ refactor. Noted that using keywords it the prefered method of passing config options to extensions. Also updated the example sto demonstrate the new prefered way as discussed in #325. --- docs/reference.txt | 16 +++++++++++++--- 1 file changed, 13 insertions(+), 3 deletions(-) diff --git a/docs/reference.txt b/docs/reference.txt index 5a7490a..1b2ef11 100644 --- a/docs/reference.txt +++ b/docs/reference.txt @@ -68,6 +68,10 @@ The following options are available on the `markdown.markdown` function: extensions=[MyExtension(), 'path.to.my.ext', 'extra'] + !!! 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. + When passing in extension instances, each class instance must be a subclass of `markdown.extensions.Extension` and any configuration options should be defined when initiating the class instance rather than using the @@ -77,7 +81,7 @@ The following options are available on the `markdown.markdown` function: class MyExtension(Extension): # define your extension here... - markdown.markdown(text, extensions=[MyExtension(configs={'option': 'value'})) + markdown.markdown(text, extensions=[MyExtension(option='value')]) 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 @@ -97,8 +101,9 @@ The following options are available on the `markdown.markdown` function: 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](#extension_configs) keyword - be used or an instance of a class be passed in. + suggested that an instance of a class be passed in or, if that's not + possible, the [extension_configs](#extension_configs) keyword + be used. !!! seealso "See Also" See the documentation of the [Extension API](extensions/api.html) for @@ -111,6 +116,11 @@ The following options are available on the `markdown.markdown` function: (as a string). When loading extensions as class instances, pass the configuration settings directly to the class when initializing it. + !!! Note + The prefered method is to pass in an instance of an extension, which + does not require use of the `extension_configs` keyword at all. + See the [extensions](#extensions) keyword for details. + The dictionary of configuration settings must be in the following format: extension_configs = {'extension_name_1': -- cgit v1.2.3