<> = Code Documentation = Please note that this page does not apply to moin2 any more. -- ThomasWaldmann <> We provide '''automatically generated''' code documentation on [[http://docs.moinmo.in/|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 * MoinSrc:MoinMoin/i18n/__init__.py - I18N support (contains the interface translation) * MoinSrc:MoinMoin/script/__init__.py - Command line utilities (see also `setup.py`) * MoinSrc:MoinMoin/stats/__init__.py - statistics (mostly from the event log) * MoinSrc: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. * MoinSrc:MoinMoin/util/__init__.py - helper modules * MoinSrc:MoinMoin/widget/__init__.py - user-interface elements * MoinSrc:MoinMoin/wikixml/__init__.py - support modules related to XML features * MoinSrc: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. MoinSrc: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. * MoinSrc:MoinMoin/action/__init__.py HelpOnActions lists all the querystrings that are handled by this module. === Page === MoinSrc: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 MoinSrc: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 MoinSrc:MoinMoin/parser/text.py for an easy example * MoinSrc: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: {{{#!python parser = Parser(text, request) 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: {{{#!python formattedText = request.redirectedOuput(parser.format, formatter) }}} === Macro === Macros embed results into a wiki page. see HelpOnMacros or MacroMarket for examples * MoinSrc: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`). * MoinSrc:MoinMoin/formatter/base.py * MoinSrc:MoinMoin/formatter/text_html.py * MoinSrc: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 Wiki: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/ 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 <>