htmltmpl: templating engine for separation of code and HTML

Easydoc is an example application that uses htmltmpl to provide flexible HTML output. It can process docstrings embedded in source file of a module and generate proper XHTML documentation from them. It's very similar to the javadoc program used by Java applications. The API documentation for htmltmpl and easydoc itself is auto-generated by easydoc.

The purpose of the program is to ease maintenance of documentation. It's very annoying to maintain more versions of documentation at once - docstrings in a source file and a HTML form of them which is much more convenient for common users. After a while the two versions always fail to be synchronized and become a maintenance nightmare.

The solution is to maintain the documentation only in form of docstrings in the source code and generate the HTML version automatically from them.

Of course, many other solutions exist for this purpose. This program was created to be similar to javadoc and as a test application for htmltmpl. The default template it uses is quite complex; it contains loops which are nested four levels deep. You can replace the default template with your own one to customize the output.

Easydoc is now part of the htmltmpl distribution and is automatically installed when you install htmltmpl. There also is a script called easy.py which provides command line interface to the module. It's included in the distribution. Run it without any parameters to view usage instructions.

The API documentation of the easydoc module can be found here.

Explanation and example

This example documented module illustrates and describes the special syntax of docstrings which easydoc requires. The syntax is similar to that of javadoc. 


""" Short one line description of the module.

    Detailed description of the module which can span more lines. You can
    use HTML tags here, but you should use only in-line tags which will not
    break the page. Do NOT use <p> or <br> tags to separate
    paragraphs. Instead use empty lines which are automatically converted
    to paragraph separators. HTML brackets which are not part of a tag
    should be written as appropriate HTML entities. All strings in form
    [ http://some.url.com ] are automatically converted to
    hyperlinks.
    
    After the detailed description comes the 'meta' section which should be
    used to give the docstring processor some structured information about
    the section which is being documented. It uses special statements which
    begin with the '@' character. This character is ignored if it isn't the
    first non-whitespace character on a line. URLs in parameters that
    specify an URL should _NOT_ be written in the special hyperlink form
    described above.

    @name             easydoc
    @version          1.00
    @website          http://htmltmpl.sourceforge.net/
    @author-name      Tomas Styblo
    @author-email     tripie@cpan.org
    @license-name     GNU GPL
    @license-url      http://www.gnu.org/licenses/gpl.html
    @require          htmltmpl ([ http://htmltmpl.sourceforge.net ])
    @require          some other prerequisite ...
"""

class Example:
    """ One line description of the class. End it with a dot if appropriate.

    Detailed description which can span more lines. You can use HTML tags
    here, but you should use only in-line tags which will not break the page.
    Do NOT use <p> or <br> tags to separate paragraphs. Instead
    use empty lines which are automatically converted to paragraph separators.
    HTML brackets which are not part of a tag should be written as appropriate
    HTML entities. Code examples must be placed inside a <pre> block.
    
    After the detailed description comes the 'meta' section which should
    be used to give the docstring processor some structured information
    about the section which is being documented. It uses special statements
    which begin with the '@' character. This character is ignored if it isn't
    the first non-whitespace character on a line.
    
    @hidden The meta section can contain some special processing instructions.
    The @hidden instruction can be used to exclude the section which is being
    documented from the resulting documentation. This is useful for private
    classes and methods.
    
    The sections marked as hidden can be included in the output if you use
    the '--with-hidden' command line option of easydoc.
    """
    
    def method(param1, param2=""):
        """ Short one line description of the method.
        
        Detailed description of the method. Same rules as for detailed
        descriptions of classes apply here.
        
        The header statement below must contain a full header of the method,
        as it appears in the code. It's used for quick overview of the
        method's parameters and their default values. Do not include the
        self parameter of methods here.

        @return Short one line description of return value.
        Here comes detailed description of the return value. It can span
        more lines and contain appropriate HTML markup. You should explicitly
        document cases when the method has no return value.

        @header
        method(param1, param2="")

        @param param1 One Line description of parameter.
        More detailed description of the 'param' parameter which again can
        span  more lines and contain HTML tags. These detailed descriptions
        are terminated by either end of the docstring or by another statement.
        
        The detailed descriptions also can consist of more paragraphs
        separated by an empty line.
        
        @param param2 One line description of parameter.
        Detailed description of the second parameter.
         
        @hidden This statement has the same meaning as in classes.
        """