From c27cbd154050c1181eac195a4b0bb19a6bbaf048 Mon Sep 17 00:00:00 2001 From: Waylan Limberg Date: Fri, 29 Aug 2014 10:57:18 -0400 Subject: Docs now use dot notation for all extensions. Except were "short names" are explained in the docs, all references to the buitlin extensions now use `markdown.extensions.*` in anticipation of #336. --- docs/cli.txt | 21 +++++++------------ docs/extensions/abbreviations.txt | 2 +- docs/extensions/attr_list.txt | 2 +- docs/extensions/code_hilite.txt | 2 +- docs/extensions/definition_lists.txt | 2 +- docs/extensions/extra.txt | 4 ++-- docs/extensions/fenced_code_blocks.txt | 2 +- docs/extensions/footnotes.txt | 2 +- docs/extensions/header_id.txt | 2 +- docs/extensions/index.txt | 38 +++++++++++++++++----------------- docs/extensions/meta_data.txt | 4 ++-- docs/extensions/nl2br.txt | 2 +- docs/extensions/sane_lists.txt | 2 +- docs/extensions/smart_strong.txt | 8 +++---- docs/extensions/smarty.txt | 2 +- docs/extensions/tables.txt | 2 +- docs/extensions/toc.txt | 4 ++-- docs/extensions/wikilinks.txt | 10 ++++----- 18 files changed, 52 insertions(+), 59 deletions(-) (limited to 'docs') diff --git a/docs/cli.txt b/docs/cli.txt index f805b5e..acad4ff 100644 --- a/docs/cli.txt +++ b/docs/cli.txt @@ -113,14 +113,7 @@ Using Extensions ---------------- To load a Python-Markdown extension from the command line use the `-x` -(or `--extension`) option. For extensions included with Python-Markdown, use -the short "Name" [documented] for that extension. - -[documented]: index.html#officially-supported-extensions - - $ python -m markdown -x footnotes text_with_footnotes.txt - -For third party extensions, the extension module must be on your `PYTHONPATH` +(or `--extension`) option. The extension module must be on your `PYTHONPATH` (see the [Extension API](extensions/api.html) for details). The extension can then be invoked by the name of that module using Python's dot syntax: @@ -128,13 +121,13 @@ then be invoked by the name of that module using Python's dot syntax: To load multiple extensions, specify an `-x` option for each extension: - $ python -m markdown -x footnotes -x codehilite input.txt + $ python -m markdown -x markdown.extensions.footnotes -x markdown.extensions.codehilite input.txt If the extension supports configuration options (see the documentation for the extension you are using to determine what settings it supports, if any), you can pass them in as well: - $ python -m markdown -x footnotes -c config.yml input.txt + $ python -m markdown -x markdown.extensions.footnotes -c config.yml input.txt The `-c` (or `--extension_configs`) option accepts a file name. The file must be in either the [YAML] or [JSON] format and contain YAML or JSON data that would map to @@ -142,12 +135,12 @@ a Python Dictionary in the format required by the [`extension_configs`][ec] keyw of the `markdown.Markdown` class. Therefore, the file `config.yaml` referenced in the above example might look like this: - footnotes: + markdown.extensions.footnotes: PLACE_MARKER: ~~~~~~~~ UNIQUE_IDS: True -Note that while the `--extension_configs` option does specify the "footnotes" extension, -you still need to load the extension with the `-x` option, or the configs for that +Note that while the `--extension_configs` option does specify the "markdown.extensions.footnotes" +extension, you still need to load the extension with the `-x` option, or the configs for that extension will be ignored. The `--extension_configs` option will only support YAML config files if [PyYaml] is @@ -157,7 +150,7 @@ 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 "footnotes(PLACE_MARKER=~~~~~~~~,UNIQUE_IDS=1)" input.txt + $ 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 diff --git a/docs/extensions/abbreviations.txt b/docs/extensions/abbreviations.txt index 070bb01..9ac7c95 100644 --- a/docs/extensions/abbreviations.txt +++ b/docs/extensions/abbreviations.txt @@ -39,7 +39,7 @@ will be rendered as: Usage ----- -See [Extensions](index.html) for general extension usage, specify `abbr` +See [Extensions](index.html) for general extension usage, specify `markdown.extensions.abbr` as the name of the extension. This extension does not accept any special configuration options. diff --git a/docs/extensions/attr_list.txt b/docs/extensions/attr_list.txt index 818fe53..01329c6 100644 --- a/docs/extensions/attr_list.txt +++ b/docs/extensions/attr_list.txt @@ -82,7 +82,7 @@ The above results in the following output: Usage ----- -See [Extensions](index.html) for general extension usage, specify `attr_list` +See [Extensions](index.html) for general extension usage, specify `markdown.extensions.attr_list` as the name of the extension. This extension does not accept any special configuration options. diff --git a/docs/extensions/code_hilite.txt b/docs/extensions/code_hilite.txt index f0648e1..c775df7 100644 --- a/docs/extensions/code_hilite.txt +++ b/docs/extensions/code_hilite.txt @@ -128,7 +128,7 @@ Lets see the source for that: Usage ----- -See [Extensions](index.html) for general extension usage, specify `codehilite` +See [Extensions](index.html) for general extension usage, specify `markdown.extensions.codehilite` as the name of the extension. See the [Library Reference](../reference.html#extensions) for information about diff --git a/docs/extensions/definition_lists.txt b/docs/extensions/definition_lists.txt index 31e8601..d7003e2 100644 --- a/docs/extensions/definition_lists.txt +++ b/docs/extensions/definition_lists.txt @@ -47,7 +47,7 @@ will be rendered as: Usage ----- -See [Extensions](index.html) for general extension usage, specify `def_list` +See [Extensions](index.html) for general extension usage, specify `markdown.extensions.def_list` as the name of the extension. This extension does not accept any special configuration options. diff --git a/docs/extensions/extra.txt b/docs/extensions/extra.txt index ace801b..bf4d12f 100644 --- a/docs/extensions/extra.txt +++ b/docs/extensions/extra.txt @@ -32,7 +32,7 @@ Usage From the Python interpreter: >>> import markdown - >>> html = markdown.markdown(text, ['extra']) + >>> html = markdown.markdown(text, ['markdown.extensions.extra']) There may be [additional extensions](index.html) that are distributed with Python-Markdown that are not included here in Extra. The features @@ -45,7 +45,7 @@ your own clone of Extra under a different name Markdown Inside HTML Blocks --------------------------- -Unlike the other Extra features, this feature is built into the markdown core and is turned on when `extra` is enabled. +Unlike the other Extra features, this feature is built into the markdown core and is turned on when `markdown.extensions.extra` is enabled. The content of any raw html block element can be Markdown-formatted simply by adding a `markdown` attribute to the opening tag. The markdown attribute will be stripped from the output, but all other attributes will be preserved. diff --git a/docs/extensions/fenced_code_blocks.txt b/docs/extensions/fenced_code_blocks.txt index bfb65d3..19999fd 100644 --- a/docs/extensions/fenced_code_blocks.txt +++ b/docs/extensions/fenced_code_blocks.txt @@ -106,7 +106,7 @@ The lines can be specified with PHP Extra's syntax: Usage ----- -See [Extensions](index.html) for general extension usage, specify `fenced_code` +See [Extensions](index.html) for general extension usage, specify `markdown.extensions.fenced_code` as the name of the extension. This extension does not accept any special configuration options. diff --git a/docs/extensions/footnotes.txt b/docs/extensions/footnotes.txt index 0f86595..40081e5 100644 --- a/docs/extensions/footnotes.txt +++ b/docs/extensions/footnotes.txt @@ -64,7 +64,7 @@ is indented consistently and any errors are more easily discernible by the autho Usage ----- -See [Extensions](index.html) for general extension usage, specify `footnotes` +See [Extensions](index.html) for general extension usage, specify `markdown.extensions.footnotes` as the name of the extension. See the [Library Reference](../reference.html#extensions) for information about diff --git a/docs/extensions/header_id.txt b/docs/extensions/header_id.txt index 90eac3b..71d65f4 100644 --- a/docs/extensions/header_id.txt +++ b/docs/extensions/header_id.txt @@ -35,7 +35,7 @@ Results in: Usage ----- -See [Extensions](index.html) for general extension usage, specify `headerid` +See [Extensions](index.html) for general extension usage, specify `markdown.extensions.headerid` as the name of the extension. See the [Library Reference](../reference.html#extensions) for information about diff --git a/docs/extensions/index.txt b/docs/extensions/index.txt index d6d41df..1052d15 100644 --- a/docs/extensions/index.txt +++ b/docs/extensions/index.txt @@ -14,13 +14,13 @@ actual source files. To use an extension, pass it to markdown with the `extensions` keyword. - markdown.markdown(some_text, extensions=[MyExtension(), 'path.to.my.ext', 'footnotes']) + markdown.markdown(some_text, extensions=[MyExtension(), 'path.to.my.ext', 'markdown.extensions.footnotes']) See the [Library Reference](../reference.html#extensions) for more details. From the command line, specify an extension with the `-x` option. - $ python -m markdown -x footnotes -x tables input.txt > output.html + $ python -m markdown -x markdown.extensions.footnotes -x markdown.extensions.tables input.txt > output.html See the [Command Line docs](../cli.html) or use the `--help` option for more details. @@ -39,23 +39,23 @@ available to you using the "name" listed in the second column below. Extension | "Name" ------------------------------------ | --------------- -[Extra] | `extra` -    [Abbreviations][] | `abbr` -    [Attribute Lists][] | `attr_list` -    [Definition Lists][] | `def_list` -    [Fenced Code Blocks][] | `fenced_code` -    [Footnotes][] | `footnotes` -    [Tables][] | `tables` -    [Smart Strong][] | `smart_strong` -[Admonition][] | `admonition` -[CodeHilite][] | `codehilite` -[HeaderId] | `headerid` -[Meta-Data] | `meta` -[New Line to Break] | `nl2br` -[Sane Lists] | `sane_lists` -[SmartyPants] | `smarty` -[Table of Contents] | `toc` -[WikiLinks] | `wikilinks` +[Extra] | `markdown.extensions.extra` +    [Abbreviations][] | `markdown.extensions.abbr` +    [Attribute Lists][] | `markdown.extensions.attr_list` +    [Definition Lists][] | `markdown.extensions.def_list` +    [Fenced Code Blocks][] | `markdown.extensions.fenced_code` +    [Footnotes][] | `markdown.extensions.footnotes` +    [Tables][] | `markdown.extensions.tables` +    [Smart Strong][] | `markdown.extensions.smart_strong` +[Admonition][] | `markdown.extensions.admonition` +[CodeHilite][] | `markdown.extensions.codehilite` +[HeaderId] | `markdown.extensions.headerid` +[Meta-Data] | `markdown.extensions.meta` +[New Line to Break] | `markdown.extensions.nl2br` +[Sane Lists] | `markdown.extensions.sane_lists` +[SmartyPants] | `markdown.extensions.smarty` +[Table of Contents] | `markdown.extensions.toc` +[WikiLinks] | `markdown.extensions.wikilinks` [Extra]: extra.html [Abbreviations]: abbreviations.html diff --git a/docs/extensions/meta_data.txt b/docs/extensions/meta_data.txt index 7ac24e2..406755b 100644 --- a/docs/extensions/meta_data.txt +++ b/docs/extensions/meta_data.txt @@ -51,7 +51,7 @@ document prior to any further processing by Markdown. Usage ----- -See [Extensions](index.html) for general extension usage, specify `meta` +See [Extensions](index.html) for general extension usage, specify `markdown.extensions.meta` as the name of the extension. This extension does not accept any special configuration options. @@ -62,7 +62,7 @@ Accessing the Meta-Data The meta-data is made available as a python Dict in the `Meta` attribute of an instance of the Markdown class. For example, using the above document: - >>> md = markdown.Markdown(extensions = ['meta']) + >>> md = markdown.Markdown(extensions = ['markdown.extensions.meta']) >>> html = md.convert(text) >>> # Meta-data has been stripped from output >>> print html diff --git a/docs/extensions/nl2br.txt b/docs/extensions/nl2br.txt index 0fe20c3..5cc070c 100644 --- a/docs/extensions/nl2br.txt +++ b/docs/extensions/nl2br.txt @@ -31,7 +31,7 @@ Example Usage ----- -See [Extensions](index.html) for general extension usage, specify `nl2br` +See [Extensions](index.html) for general extension usage, specify `markdown.extensions.nl2br` as the name of the extension. This extension does not accept any special configuration options. diff --git a/docs/extensions/sane_lists.txt b/docs/extensions/sane_lists.txt index 13fa9fe..8f713d0 100644 --- a/docs/extensions/sane_lists.txt +++ b/docs/extensions/sane_lists.txt @@ -67,7 +67,7 @@ In all other ways, Sane Lists should behave as normal Markdown lists. Usage ----- -See [Extensions](index.html) for general extension usage, specify `sane_lists` +See [Extensions](index.html) for general extension usage, specify `markdown.extensions.sane_lists` as the name of the extension. This extension does not accept any special configuration options. diff --git a/docs/extensions/smart_strong.txt b/docs/extensions/smart_strong.txt index 06b9c9a..e2e5458 100644 --- a/docs/extensions/smart_strong.txt +++ b/docs/extensions/smart_strong.txt @@ -23,19 +23,19 @@ Example >>> import markdown >>> markdown.markdown('Text with double__underscore__words.', \ - extensions=['smart_strong']) + extensions=['markdown.extensions.smart_strong']) u'

Text with double__underscore__words.

' >>> markdown.markdown('__Strong__ still works.', \ - extensions=['smart_strong']) + extensions=['markdown.extensions.smart_strong']) u'

Strong still works.

' >>> markdown.markdown('__this__works__too__.', \ - extensions=['smart_strong']) + extensions=['markdown.extensions.smart_strong']) u'

this__works__too.

' Usage ----- -See [Extensions](index.html) for general extension usage, specify `smart_strong` +See [Extensions](index.html) for general extension usage, specify `markdown.extensions.smart_strong` as the name of the extension. This extension does not accept any special configuration options. diff --git a/docs/extensions/smarty.txt b/docs/extensions/smarty.txt index 1f14fc7..a1b8d6e 100644 --- a/docs/extensions/smarty.txt +++ b/docs/extensions/smarty.txt @@ -57,7 +57,7 @@ Use e.g. the following config to get correct quotes for the German language: Usage ----- -See [Extensions](index.html) for general extension usage, specify `smarty` +See [Extensions](index.html) for general extension usage, specify `markdown.extensions.smarty` as the name of the extension. See the [Library Reference](../reference.html#extensions) for information about diff --git a/docs/extensions/tables.txt b/docs/extensions/tables.txt index 46e8437..759772a 100644 --- a/docs/extensions/tables.txt +++ b/docs/extensions/tables.txt @@ -52,7 +52,7 @@ will be rendered as: Usage ----- -See [Extensions](index.html) for general extension usage, specify `tables` +See [Extensions](index.html) for general extension usage, specify `markdown.extensions.tables` as the name of the extension. This extension does not accept any special configuration options. diff --git a/docs/extensions/toc.txt b/docs/extensions/toc.txt index 4d2d3c0..7b5d119 100644 --- a/docs/extensions/toc.txt +++ b/docs/extensions/toc.txt @@ -44,7 +44,7 @@ would generate the following output: Usage ----- -See [Extensions](index.html) for general extension usage, specify `toc` +See [Extensions](index.html) for general extension usage, specify `markdown.extensions.toc` as the name of the extension. See the [Library Reference](../reference.html#extensions) for information about @@ -65,7 +65,7 @@ The following options are provided to configure the output: ## Header 2 ''' - >>> md = markdown.Markdown(extensions=['toc']) + >>> md = markdown.Markdown(extensions=['markdown.extensions.toc']) >>> html = md.convert(text) >>> render_some_template(context={'body': html, 'toc': md.toc}) diff --git a/docs/extensions/wikilinks.txt b/docs/extensions/wikilinks.txt index 795ebb4..4c31eac 100644 --- a/docs/extensions/wikilinks.txt +++ b/docs/extensions/wikilinks.txt @@ -46,7 +46,7 @@ becomes Usage ----- -See [Extensions](index.html) for general extension usage, specify `wikilinks` +See [Extensions](index.html) for general extension usage, specify `markdown.extensions.wikilinks` as the name of the extension. See the [Library Reference](../reference.html#extensions) for information about @@ -78,7 +78,7 @@ For an example, let us suppose links should always point to the subdirectory `/wiki/` and end with `.html` >>> html = markdown.markdown(text, - ... ['wikilinks(base_url=/wiki/,end_url=.html)'] + ... ['markdown.extensions.wikilinks(base_url=/wiki/,end_url=.html)'] ... ) The above would result in the following link for `[[WikiLink]]`. @@ -94,14 +94,14 @@ could also pass in a callable which must accept three arguments (``label``, return url md = markdown.Markdown( - extensions=['wikilinks], - extension_configs={'wikilinks' : [('build_url', my_url_builder)]} + extensions=['markdown.extensions.wikilinks], + extension_configs={'markdown.extensions.wikilinks' : [('build_url', my_url_builder)]} ) The option is also provided to change or remove the class attribute. >>> html = markdown.markdown(text, - ... ['wikilinks(html_class=myclass)'] + ... ['markdown.extensions.wikilinks(html_class=myclass)'] ... ) Would cause all wikilinks to be assigned to the class `myclass`. -- cgit v1.2.3