Code Documentation

Please note that this page does not apply to moin2 any more. -- ThomasWaldmann 2011-03-20 13:39:37

We provide automatically generated code documentation on moin documentation. For that we use epydoc. It's similar to the famous Doxygen.

If you want to create code documentation like this for repositories not listed on the documentation website yourself, you can clone the repository (e.g.: hg.moinmo.in/moin/2.0-storage) and create the documentation by calling

make epydoc

in the root folder of your local repository. For sure epydoc has to be installed on your system.

What happens

The standard call graph of MoinMoin (simplified):

• moin.cgi (in .../cgi-bin/)

  • creates and .run()s RequestCGI object (.../MoinMoin/request/CGI.py)

• RequestCGI (based on RequestBase)

  • decides what pagename (url) or action (post) was requested and invokes either:

    • Page().send_page() to create normal pages

    • MoinMoin.action.getHandler() is used to get a handler() for the actions

Pages

• Page(name).send_page(request)

  • loads the raw page (into body)

  • decides what formatter to use (default is text_html formatter)

  • creates formatter (or uses default from Request)

  • reads processing instructions at the top of the page (see HelpOnProcessingInstructions)

  • sends page header if needed
  • decides what Parser to use (default is 'wiki' parser)

  • creates Parser object

  • calls send_page_content() to

    • use a cached page if possible

    • use Parser(body, request).format(formatter) to create the page if not

    • send the page body
  • sends footnotes if any
  • sends footer if needed

• Parser(rawtext, request).format(formatter)

  • The code says: "For each line, scan through looking for magic strings, outputting verbatim any intervening text."
  • parses rawtext
  • calls formatter methods to translate the pieces into the output language (normally HTML)
  • calls the macros found in the page
  • creates and calls parsers if needed

• request.write(text)

  • sends the parts of the page to the client

Actions

• MoinMoin.action.getHandler() first looks for a function called do_'action' (eg do_edit() is called to edit a page)

• if that fails it tries to find a action plugin

Packages

• MoinMoin - the main package contains the core code, and some helper modules

• MoinMoin/i18n/__init__.py - I18N support (contains the interface translation)

• MoinMoin/script/__init__.py - Command line utilities (see also setup.py)

• MoinMoin/stats/__init__.py - statistics (mostly from the event log)

• MoinMoin/support/__init__.py - Smaller third-party modules copied into the MoinMoin code base, in order to not create unnecessary dependencies or to fix bugs in Python stdlib.

• MoinMoin/util/__init__.py - helper modules

• MoinMoin/widget/__init__.py - user-interface elements

• MoinMoin/wikixml/__init__.py - support modules related to XML features

• MoinMoin/_tests/__init__.py - unit tests, not installed via setup.py

Tour of the most important classes

Request

Request sub classes handle all the information that came from the client. There is a request sub class for each type of server environment, hiding the differences between different servers behind a common API. The generation of the request object is one of the first things done by MoinMoin.

MoinMoin/request/__init__.py

Action

The second thing that happens is to decide what action to perform. Actions are on the toplevel of the decision making process of what MoinMoin should do with a request. Action may do every thing. The default action is viewing a page.

• MoinMoin/action/__init__.py HelpOnActions lists all the querystrings that are handled by this module.

Page

MoinMoin/Page.py represents an unchangeable wiki page. Generating a Page object with Page(page_name, **keywords) is a lean operation. Therefore it is absolutely ok to do e.g. the_url = Page(name).url()

To show the page content use Page.send_page(request, msg=None, **keywords).

Note: Page represents both a page with multiple revisions, and a single revision of a page, depending on how you create it. It is also responsible for fetching a page list when used as the root page of the wiki.

Note: send_page is responsible to parsing the page processing instructions, executing the page cache or formatting the page content, sending the header and footer, any many other roles.

PageEditor

For changeable wiki pages there is MoinMoin/PageEditor.py a sub-class of Page. Use PageEditor.send_editor(request, msg=None, **keywords) to send the Editor to the user. The PageEditor class is responsible for persistence of the page data and updating the current revision pointer.

By now Page/PageEditor does the user interface too. send_page() and send_editor() are self-contained and it is safe to quit after them.

Parser

Parser parses text, format it using a formatter and write it to request. They normally are instantiated by Page and used to format page content.

• see MoinMoin/parser/text.py for an easy example

• MoinMoin/parser/text_moin_wiki.py is the default parser processing WikiMarkup

Write new Parsers to support a completely new input format. See ParserMarket.

Example - using a parser to format text:

   1 parser = Parser(text, request)
   2 parser.format(formatter)

If you want to format the text into a buffer, use request.redirectedOutput(), which redirect the output of the function you send it to a buffer, and make sure to redirect back to the real file even if an exception was raised.

Example - parsing into a buffer:

   1 formattedText = request.redirectedOuput(parser.format, formatter)

Macro

Macros embed results into a wiki page. see HelpOnMacros or MacroMarket for examples

• MoinMoin/macro/__init__.py

Formatter

Formatters are usually used to generate output. The default formatter produces HTML. There is a format action which shows the page with a different formatter. It uses the mimetype parameter (e.g. text/xml).

• MoinMoin/formatter/base.py

• MoinMoin/formatter/text_html.py

• MoinMoin/formatter/__init__.py

Because some parts of MoinMoin still don't use the formatter properly or produce only HTML and use formatter.rawHTML(), non HTML formatter cannot translate every thing into another output language.

See FormatterRefactoring for details.

Formatter are also used to generate other products from parsed text, for example, pagelinks formatter does not format anything, but create a list of links appearing in the parsed page.

The parser and the formatter use the BuilderPattern. The parser is the director using various builders to create different kinds of output text or other products.

Plugins

Moin can get extended by a wiki admin even if he has no write access to the MoinMoin code directory. Extension plugins get imported from the wiki's data/plugin/<plugintype> directory (plugintype = action, macro, parser, theme, xmlrpc).

If you want this and related pages to grow, you have to help, because I don't have the time to provide all this info. So unless a few experienced long-time MoinMoin developers (or newbies exploring the source) help with this, not much will happen here. Asking helps too, since it indicates the topics to put focus on. -- JürgenHermann 2002-07-17 16:20:58