htmltmpl - easydoc
Author: Tomas Styblo (tripie@cpan.org)

htmltmpl: templating engine for separation of code and HTML

HOMEPAGE OVERVIEW THE LANGUAGE API DOCS GETTEXT SUPPORT PYTHON VERSION PYTHON EASYDOC PHP VERSION MAILING LIST PUBLIC CVS HTML::TEMPLATE | 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

## 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.
            """