From: Holger Schurig Date: Fri, 26 Jun 2009 08:02:22 +0000 (+0200) Subject: doc: move plugin documentation into plugin/ directory X-Git-Url: https://oss.titaniummirror.com/gitweb?p=oss-web.git;a=commitdiff_plain;h=96a3e28269799582c1d618aba29cfd14c926b269 doc: move plugin documentation into plugin/ directory While at it: fix typos in the "linktitle:" tags. --- diff --git a/in/hierarchy.md b/in/hierarchy.md deleted file mode 100644 index cace962..0000000 --- a/in/hierarchy.md +++ /dev/null @@ -1,177 +0,0 @@ -title: Generate hierarchy -linktitly: Hierarchy -parent: Plugins -ctime: 2009-06-26 - -This is one of the more complex plugins, used to generate menus and -breadcrumbs. For this, it reads certain keyword from the -[[pageformat]], built an internal parent-child representation. - -This is later used for by the functions "`get_breadcrumbs()`" and -"`get_sidemenu()`", which you call from the [[template_mako]]. - -= Page attributes = - -At the "`scan`" [[hook|hooks]], the plugin looks for entries like: - - parent: Home - -or - - childs: Cmdline, Inheritance - -Here's an example of five pages with different attributes: - ---- - - title: Homepage - linktitle: Home - ---- - - title: Impressum - parent: Home - ---- - - title: Job - parent: Home - ---- - - title: CV - parent: Job - ---- - - title: Knowledge - parent: Job - ---- - -= Internal representation = - -the plugin would populate the variables "`_childs`" and "`_parent`" like this: - - _parent = { - 'Impressum': 'Home', - 'CV': 'Job', - 'Knowledge': 'Job', - 'Job': 'Home' - } - - _childs = { - 'Home': [(100, 'Job'), - (100, 'Impressum')], - 'Job': [(100, 'CV'), - (100, 'Knowledge')]} - -That's all you need to generate a sidemap, breadcrumbs or a side-menu. - -The pages are first ordered by some number, then by the "`linktitle`". If -a page has no "`linktitle:`" attribute, then the normal title will be used -instead. - -If you want to modify the sort-order, simply specify a "`order: 200`" in the -page itself. - -= Generation of breadcrumbs = - -This is done via a suitable [[template_mako]]. The template uses the -function "`get_breadcrumbs()`" and returns (linktitle, link) tuples. As a -bonus: all the links are always relative to the calling page. - -Here's a sample Mako template excerpt: - - \ - - -= Generation of a side-menu = - -This again is done via a suitable [[template_mako]]. The -template uses the function "`get_sidemenu()`" and returns (level, -part_of_path, is_current, title, link) tuples. Again all links are relative -to the calling page. - -* "`level`" is the indendation level, starting with 0. You can use this for - CSS "`id=`" or "`class`" attributes -* "`part_of_path`" is a flag telling you if the mentioned page is part - of your path, i.e. if the specified page is in the breadcrumbs. -* "`is_current`" is a flag marking the current page. -* "`title`" is the full title for the page -* "`link`" is the relative URL to the page - -Here's a sample Mako template excerpt that converts this into a HTML menu: - - - -= Generate a list of recently changed pages = - -To get a list of recently changed pages, do this: - - <% - history = get_recently()) - %> - % if len(history)>1: -

Recent changed

- % for page, link in history: - % if page.mtime > page.ctime: - Modified ${format_date(page.mtime)}\ - % else: - Created ${format_date(page.ctime)}\ - % endif - : ${page.title | entity}
- % endfor - % endif - - -= Generate a sitemap = - -To generate a site map for your whole project, do something like -this: - - <% - site = get_sitemap() - %> - - -Now you'd need to use CSS to indent the entries. If you prefer a more -normal "`<% lvl -= 1 %> - % endwhile diff --git a/in/link.md b/in/link.md deleted file mode 100644 index f545011..0000000 --- a/in/link.md +++ /dev/null @@ -1,47 +0,0 @@ -title: Create HTML links -linktitle: Linkify -parent: Plugins -ctime: 2009-06-26 - -This plugin converts strings in the form - -
[[url]]
-[[text|url]]
-[[#anchor]]
-[[text|url#anchor]]
-
- -into HTML `` tags. - -= Automatic linkification = - -Instead of an URL you can also specify the following things: - -* the page title -* the short link title -* the basename of the file (filename without extension and directory name) - -In this case the link plugin will search throught all pages and take the -first match. - -Example: - -Suppose you've two file "`testfile.md`" and "`testfile2.md`" which looks like this: - - title: Foo - linktitle: bar - ---- - - title: Test2 - -then the following two links - -
[[Foo]]
-[[bar]]
-[[testfile2]]
-
- -will produce two links to the first file and one link to the second file. -All text part of the HTML link will be substituted with the title of the -referred pages, except you specify a text by yourself. diff --git a/in/plugins.md b/in/plugins.md deleted file mode 100644 index 588e653..0000000 --- a/in/plugins.md +++ /dev/null @@ -1,25 +0,0 @@ -title: Plugins -parent: Webber -ctime: 2009-06-26 - -Webber doesn't do much on it's own. Almost all the real work is delegated -to plugins. Those plugins do: - -* Read files and generate HTML snippets ([[read_rst.py|read_rst]], - [[read_markdown.py|read_markdown]], [[read_html.py|read_html]]) - or copy files verbatim, e.g. for graphics - ([[read_copyonly.py|read_copyonly]]) -* Update internal state or modify HTML snippets - ([[hierarchy.py|hierarchy]], [[link.py|link]]) -* Create HTML pages ([[template_mako.py|template_mako]]) - -There's another plugin there ([[skeleton.py|skeleton]], which is -is just a demo for plugin-programmers. - -Plugins simply reside in the "`plugins/`" directory. However, webber -doesn't load all of them automatically. Instead you specify in the -configuration file [[webber.conf|configuration]] which -plugins you want. - -Once plugins are loaded, webber orchestrates the work of itself and -all plugins via [[hooks]]. diff --git a/in/plugins/hierarchy.md b/in/plugins/hierarchy.md new file mode 100644 index 0000000..15388b1 --- /dev/null +++ b/in/plugins/hierarchy.md @@ -0,0 +1,177 @@ +title: Generate hierarchy +linktitle: hierarchy.py +parent: Plugins +ctime: 2009-06-26 + +This is one of the more complex plugins, used to generate menus and +breadcrumbs. For this, it reads certain keyword from the +[[pageformat]], built an internal parent-child representation. + +This is later used for by the functions "`get_breadcrumbs()`" and +"`get_sidemenu()`", which you call from the [[template_mako]]. + += Page attributes = + +At the "`scan`" [[hook|hooks]], the plugin looks for entries like: + + parent: Home + +or + + childs: Cmdline, Inheritance + +Here's an example of five pages with different attributes: + +--- + + title: Homepage + linktitle: Home + +--- + + title: Impressum + parent: Home + +--- + + title: Job + parent: Home + +--- + + title: CV + parent: Job + +--- + + title: Knowledge + parent: Job + +--- + += Internal representation = + +the plugin would populate the variables "`_childs`" and "`_parent`" like this: + + _parent = { + 'Impressum': 'Home', + 'CV': 'Job', + 'Knowledge': 'Job', + 'Job': 'Home' + } + + _childs = { + 'Home': [(100, 'Job'), + (100, 'Impressum')], + 'Job': [(100, 'CV'), + (100, 'Knowledge')]} + +That's all you need to generate a sidemap, breadcrumbs or a side-menu. + +The pages are first ordered by some number, then by the "`linktitle`". If +a page has no "`linktitle:`" attribute, then the normal title will be used +instead. + +If you want to modify the sort-order, simply specify a "`order: 200`" in the +page itself. + += Generation of breadcrumbs = + +This is done via a suitable [[template_mako]]. The template uses the +function "`get_breadcrumbs()`" and returns (linktitle, link) tuples. As a +bonus: all the links are always relative to the calling page. + +Here's a sample Mako template excerpt: + + \ + + += Generation of a side-menu = + +This again is done via a suitable [[template_mako]]. The +template uses the function "`get_sidemenu()`" and returns (level, +part_of_path, is_current, title, link) tuples. Again all links are relative +to the calling page. + +* "`level`" is the indendation level, starting with 0. You can use this for + CSS "`id=`" or "`class`" attributes +* "`part_of_path`" is a flag telling you if the mentioned page is part + of your path, i.e. if the specified page is in the breadcrumbs. +* "`is_current`" is a flag marking the current page. +* "`title`" is the full title for the page +* "`link`" is the relative URL to the page + +Here's a sample Mako template excerpt that converts this into a HTML menu: + + + += Generate a list of recently changed pages = + +To get a list of recently changed pages, do this: + + <% + history = get_recently()) + %> + % if len(history)>1: +

Recent changed

+ % for page, link in history: + % if page.mtime > page.ctime: + Modified ${format_date(page.mtime)}\ + % else: + Created ${format_date(page.ctime)}\ + % endif + : ${page.title | entity}
+ % endfor + % endif + + += Generate a sitemap = + +To generate a site map for your whole project, do something like +this: + + <% + site = get_sitemap() + %> + + +Now you'd need to use CSS to indent the entries. If you prefer a more +normal "`<% lvl -= 1 %> + % endwhile diff --git a/in/plugins/index.md b/in/plugins/index.md new file mode 100644 index 0000000..588e653 --- /dev/null +++ b/in/plugins/index.md @@ -0,0 +1,25 @@ +title: Plugins +parent: Webber +ctime: 2009-06-26 + +Webber doesn't do much on it's own. Almost all the real work is delegated +to plugins. Those plugins do: + +* Read files and generate HTML snippets ([[read_rst.py|read_rst]], + [[read_markdown.py|read_markdown]], [[read_html.py|read_html]]) + or copy files verbatim, e.g. for graphics + ([[read_copyonly.py|read_copyonly]]) +* Update internal state or modify HTML snippets + ([[hierarchy.py|hierarchy]], [[link.py|link]]) +* Create HTML pages ([[template_mako.py|template_mako]]) + +There's another plugin there ([[skeleton.py|skeleton]], which is +is just a demo for plugin-programmers. + +Plugins simply reside in the "`plugins/`" directory. However, webber +doesn't load all of them automatically. Instead you specify in the +configuration file [[webber.conf|configuration]] which +plugins you want. + +Once plugins are loaded, webber orchestrates the work of itself and +all plugins via [[hooks]]. diff --git a/in/plugins/link.md b/in/plugins/link.md new file mode 100644 index 0000000..8a0af05 --- /dev/null +++ b/in/plugins/link.md @@ -0,0 +1,47 @@ +title: Create HTML links +linktitle: link.py +parent: Plugins +ctime: 2009-06-26 + +This plugin converts strings in the form + +
[[url]]
+[[text|url]]
+[[#anchor]]
+[[text|url#anchor]]
+
+ +into HTML `` tags. + += Automatic linkification = + +Instead of an URL you can also specify the following things: + +* the page title +* the short link title +* the basename of the file (filename without extension and directory name) + +In this case the link plugin will search throught all pages and take the +first match. + +Example: + +Suppose you've two file "`testfile.md`" and "`testfile2.md`" which looks like this: + + title: Foo + linktitle: bar + +--- + + title: Test2 + +then the following two links + +
[[Foo]]
+[[bar]]
+[[testfile2]]
+
+ +will produce two links to the first file and one link to the second file. +All text part of the HTML link will be substituted with the title of the +referred pages, except you specify a text by yourself. diff --git a/in/plugins/read_copyonly.md b/in/plugins/read_copyonly.md new file mode 100644 index 0000000..939f4b2 --- /dev/null +++ b/in/plugins/read_copyonly.md @@ -0,0 +1,18 @@ +title: Read and copy binary files +linktitle: read_copyonly.py +parent: Plugins +ctime: 2009-06-26 + +This plugin copies files (e.g. graphics files) into the destination +folder. + +To configure which files should be copied you modify +[[webber.conf|configuration.html]]. An example snippet migth be: + + copy_files: [ + "*.png", + "*.jpg", + "*.gif", + "*.css", + "robots.txt", + ] diff --git a/in/plugins/read_html.md b/in/plugins/read_html.md new file mode 100644 index 0000000..829a30d --- /dev/null +++ b/in/plugins/read_html.md @@ -0,0 +1,22 @@ +title: Read HTML +linktitle: read_html.py +parent: Plugins +ctime: 2009-06-26 + +This plugin reads HTML snippets from "`*.html`" files. + +Please note that currently the plugin assumes that this is a HTML snippet. +That means: the snippes should only contain what is inside "``" and +"``", but without those tags themselfes. + +A sample "`test.html`" document looks like this: + + title: Job + parent: Home + ctime: 2008-10-01 + +

What I did in the past:

+ + +You'll find more about "`title:`", "`parent:`" and "`ctime:`" in the +[[page format|pageformat.html]] description. diff --git a/in/plugins/read_markdown.md b/in/plugins/read_markdown.md new file mode 100644 index 0000000..d042adf --- /dev/null +++ b/in/plugins/read_markdown.md @@ -0,0 +1,40 @@ +title: Read Markdown +linktitle: read_markdown.py +parent: Plugins +ctime: 2009-06-26 + +This plugin reads "`*.md`" files and converts them to HTML. + +"[[Markdown|http://daringfireball.net/projects/markdown/]]" is a wiki-like +text format. The plugin "`read_markdown.py`" doesn't use the +standard Python module "`markdown`", but instead the faster and simpler +[[markdown2|http://code.google.com/p/python-markdown2/]] modoule. + +A sample "`test.md`" document looks like this: + + title: Impressum + parent: Home + ctime: 2008-10-01 + + # Address + + Mario Marionetti + 10, Mariott St + Marioland 1007 + + Don't send me spam, *ever*! + +You'll find more about "`title:`", "`parent:`" and "`ctime:`" in the +[[page format|pageformat.html]] description. + += Modifications = + +This implementation is based on python-markdown2 version 1.0.1.12, but has been +changed this way: + +* file-vars (emacs-style settings inside the file) have been disabled +* "Standardize line endings" removed +* call to _do_links() removed (we have the [[linkify|link.html]] pass for + this) +* logging removed +* allow "= Header =" in addition to "# Header #" diff --git a/in/plugins/read_rst.md b/in/plugins/read_rst.md new file mode 100644 index 0000000..827c67a --- /dev/null +++ b/in/plugins/read_rst.md @@ -0,0 +1,28 @@ +title: Read RST +linktitle: read_rst.py +parent: Plugins +ctime: 2009-06-26 + +This plugin reads "`*.rst`" files and converts them to HTML. + +"RST" is the abbreviation for +[[reStructuredText|http://docutils.sourceforge.net/rst.html]], a format +common for many python programmers. The plugin "`read_rst.py`" uses the +standard Python module "`docutils`" to convert RST into HTML. A sample +"`test.rst`" document looks like this: + + title: Impressum + parent: Home + ctime: 2008-10-01 + + Address + ======= + + |Mario Marionetti + |10, Mariott St + |Marioland 1007 + + Don't send me spam, *ever*! + +You'll find more about "`title:`", "`parent:`" and "`ctime:`" in the +[[page format|pageformat.html]] description. \ No newline at end of file diff --git a/in/plugins/skeleton.md b/in/plugins/skeleton.md new file mode 100644 index 0000000..316053f --- /dev/null +++ b/in/plugins/skeleton.md @@ -0,0 +1,6 @@ +title: Sample plugin skeleton +linktitle: skeleton.py +parent: Plugins +ctime: 2009-06-26 + +TODO diff --git a/in/plugins/template_mako.md b/in/plugins/template_mako.md new file mode 100644 index 0000000..45528bb --- /dev/null +++ b/in/plugins/template_mako.md @@ -0,0 +1,6 @@ +title: Web page template +linktitle: template_mako.py +parent: Plugins +ctime: 2009-06-26 + +TODO diff --git a/in/read_copyonly.md b/in/read_copyonly.md deleted file mode 100644 index bd4a5dc..0000000 --- a/in/read_copyonly.md +++ /dev/null @@ -1,18 +0,0 @@ -title: Read and copy binary files -linktitle: Read binaries -parent: Plugins -ctime: 2009-06-26 - -This plugin copies files (e.g. graphics files) into the destination -folder. - -To configure which files should be copied you modify -[[webber.conf|configuration.html]]. An example snippet migth be: - - copy_files: [ - "*.png", - "*.jpg", - "*.gif", - "*.css", - "robots.txt", - ] diff --git a/in/read_html.md b/in/read_html.md deleted file mode 100644 index 7fac0e7..0000000 --- a/in/read_html.md +++ /dev/null @@ -1,21 +0,0 @@ -title: Read HTML -parent: Plugins -ctime: 2009-06-26 - -This plugin reads HTML snippets from "`*.html`" files. - -Please note that currently the plugin assumes that this is a HTML snippet. -That means: the snippes should only contain what is inside "``" and -"``", but without those tags themselfes. - -A sample "`test.html`" document looks like this: - - title: Job - parent: Home - ctime: 2008-10-01 - -

What I did in the past:

- - -You'll find more about "`title:`", "`parent:`" and "`ctime:`" in the -[[page format|pageformat.html]] description. diff --git a/in/read_markdown.md b/in/read_markdown.md deleted file mode 100644 index a23955e..0000000 --- a/in/read_markdown.md +++ /dev/null @@ -1,39 +0,0 @@ -title: Read Markdown -parent: Plugins -ctime: 2009-06-26 - -This plugin reads "`*.md`" files and converts them to HTML. - -"[[Markdown|http://daringfireball.net/projects/markdown/]]" is a wiki-like -text format. The plugin "`read_markdown.py`" doesn't use the -standard Python module "`markdown`", but instead the faster and simpler -[[markdown2|http://code.google.com/p/python-markdown2/]] modoule. - -A sample "`test.md`" document looks like this: - - title: Impressum - parent: Home - ctime: 2008-10-01 - - # Address - - Mario Marionetti - 10, Mariott St - Marioland 1007 - - Don't send me spam, *ever*! - -You'll find more about "`title:`", "`parent:`" and "`ctime:`" in the -[[page format|pageformat.html]] description. - -= Modifications = - -This implementation is based on python-markdown2 version 1.0.1.12, but has been -changed this way: - -* file-vars (emacs-style settings inside the file) have been disabled -* "Standardize line endings" removed -* call to _do_links() removed (we have the [[linkify|link.html]] pass for - this) -* logging removed -* allow "= Header =" in addition to "# Header #" diff --git a/in/read_rst.md b/in/read_rst.md deleted file mode 100644 index 43edc7a..0000000 --- a/in/read_rst.md +++ /dev/null @@ -1,27 +0,0 @@ -title: Read RST -parent: Plugins -ctime: 2009-06-26 - -This plugin reads "`*.rst`" files and converts them to HTML. - -"RST" is the abbreviation for -[[reStructuredText|http://docutils.sourceforge.net/rst.html]], a format -common for many python programmers. The plugin "`read_rst.py`" uses the -standard Python module "`docutils`" to convert RST into HTML. A sample -"`test.rst`" document looks like this: - - title: Impressum - parent: Home - ctime: 2008-10-01 - - Address - ======= - - |Mario Marionetti - |10, Mariott St - |Marioland 1007 - - Don't send me spam, *ever*! - -You'll find more about "`title:`", "`parent:`" and "`ctime:`" in the -[[page format|pageformat.html]] description. \ No newline at end of file diff --git a/in/skeleton.md b/in/skeleton.md deleted file mode 100644 index daed88b..0000000 --- a/in/skeleton.md +++ /dev/null @@ -1,6 +0,0 @@ -title: Sample plugin skeleton -linktitly: Skeleton -parent: Plugins -ctime: 2009-06-26 - -TODO diff --git a/in/template_mako.md b/in/template_mako.md deleted file mode 100644 index 0b1b1d8..0000000 --- a/in/template_mako.md +++ /dev/null @@ -1,6 +0,0 @@ -title: Web page template -linktitly: HTML Template -parent: Plugins -ctime: 2009-06-26 - -TODO