MoinMoin: SelfdocumentingPlugins

Short description

Plugins (macros, parsers (may be actions)) should come with their own documentation. MoinMoin should be able to build help pages out of them and offer direct help to the user while editing.

• Stuff needed:

  • prototype like [[TableOfContents([maxdepth])]], defaults to [[Marconame]], #!parsername, #format parsername

  • short description: "Inserts a table of contents of this page"
  • long despription (2-4 sentences: "Inserts a table of contents of this page. Optional integer parameter limits the level of headings shown."

Implementation ideas

• macros
  • variables in the modules for real plugins

    • prototype

    • short_description

    • full_description

  • some magic for the builtins (dicts? see dependencies)

  • API
    • No more wikimacro/action/whatever stuff please!

      • wikimacro.get_prototype(macroname)

      • wikimacro.get_short_description(macroname)

      • wikimacro.get_full_description(macroname)

    • Instead:
      • Each macro will be a class, a subclass of Macro, which contain general stuff that all macros need
      • Each macro will implement only the specific stuff need for the macro
      • Each macro will implement the online help features

      • Possible layout:

        Plugin - base class for all types of plugins
            Macro - base class for all macros/parsers, handle argument parsing etc.
                YourMacro

• parser
  • same as macros
• processors
  • don't put work into them - depricated, drop?

Use HelpOnMacros

What about extracting the macro help out of the HelpOnMacros page? That would give a simple method of i18n and an easy way of maintaining it. External macros could offer their help with in their file ofcause.

The problem is HelpOnMacros does not help at all. For each macro we need few lines of help, like this text (copied from NewPage.py):

    """ NewPage - create new pages

    Let you create new page using optional template, button text
    and parent page (for automatic subpages).

    Usage:

        [[NewPage(template, buttonLabel, parentPage)]]
        
    Examples:

        [[NewPage]]

            Create an input field with 'Create New Page' button. The new
            page will not use a template.

        [[NewPage(BugTemplate, Create New Bug, MoinMoinBugs)]]
        
            Create an input field with button labeled 'Create New
            Bug'.  The new page will use the BugTemplate template,
            and create the page as a subpage of MoinMoinBugs.
    """

Less then that is not enough. Reading the source is not an option for most users.

Help text should be formatted in rst to be compatible with epydoc, and we can parse it for the wiki display using rest parser.

I do have already a lot of comments on my parsers/macros and I am interested to change them for this. Please could you show some kind of template. -- ReimarBauer 2005-08-30 06:27:14

• Just use rst in your docstrings. See HelpOnParsers/ReStructuredText/RstPrimer or http://docutils.sourceforge.net/docs/user/rst/quickstart.html

I18N

• we need plugins for i18n to allow plugins to bring their own i18n.
• which format to use (Is any format needed other than the .po/.mo files? Using something for which tools exist is best. They might not be ideal, but they're something that translators are accustomed to.)
• needs a easy way to integrate it with the main i18n files when the plugin ias merged to the std distribution
• should be easy to edit an extend with new languages
• should be optimized for few term and lots of lanuages
• may be only one file for all languages or even as part of the plugin file

• {term_en -> {lang -> translation}} ?

User interface

• macros

  • HelpOnMacro([name])

  • HelpOnParser([name])

  • HelpOnExtension([name])

    • Macros and parser unified? see UnifyParsersAndMacros

  • HelpOnAction([name])

Overlooking that all, that doesn't look like going into 1.5, because it simply is a too big change and it isn't even clear yet, how to do it best. -- ThomasWaldmann 2005-09-23 18:55:41

I think on a simple action macro at the moment which I could add -- ReimarBauer 2005-09-25 20:22:18

• lists parsers and macros in a pull down menu
• if one is selected the comments are listed

see ActionMarket/HelpOn -- ReimarBauer 2005-10-15 19:44:32

I Suggest thatan info about a plugin is accessible via SystemInfo where all plugins are listed (the names should be clickable)

• In some wikis SystemInfo is disabled

CategoryFeatureRequest