|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.
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 firstname.lastname@example.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. """