README for the eric3-doc documentation generator

    eric3-doc is the documentation generator of the eric3 IDE. Source code documentation
    may be included as ordinary Python doc-strings or as documentation comments. For
    Quixote Template file (PTL) only documentation comments are available due to
    the inner workings of Quixote. Documentation comments start with the string ###,
    followed by the contents and ended by ###. Every line of the documentation comments
    contents must start with a # (see example below).
    
    The documentation consist of two parts. The first part is the description of the module, class,
    function or method. The second part, separated from the first by a blank line, consists of one
    or more tags. These are described below.
    
    eric3-doc produces HTML files from the documentation found within the source files scaned.
    It understand the following commandline parameters.
    
    -p prefix -- Prepend given prefix to file names.
    
    -o directory -- Generate files in the named directory.
    
    -R, -r -- Perform a recursive search for Python files.
    
    -e directory -- Specify a directory basename to be excluded.
        This option may be repeated multiple times.
    
    -i -- Don't generate index files.
    
    Just type "eric3-doc" to get some usage information.
    
    Description
    
    The descriptions are HTML fragments and may contain most standard HTML. The
    description text is included in the output wrapped in P tags, but unchanged otherwise.
    Paragraphs have to be separated by a blank line. Reserved HTML entities (<, > and &)
    and the at-sign at the beginning of a line, if that line doesn't contain a tag (see below)
    must be properly escaped.
    
    Tags
    
        The documentation string or documentation comment can contain tags. an at-sign (@)
        at the beginning of the line is used to indicate a tag. The text before the first tag is the
        description of a module, class, method or function.
        
        Docstring:
            """
            This is line one which gets included as a short description.
            All additional lines are included into the full description.
            
            @param param1 first parameter
            @exception ValueError list entry wasn't found
            @return flag indicating success
            """
            
        Documentation comment:
            ###
            # This is line one which gets included as a short description.
            # All additional lines are included into the full description.
            #
            # @param param1 first parameter
            # @exception ValueError list entry wasn't found
            # @return flag indicating success
            ###
    
    The @param tag
    
        This tag is used to describe a function or method argument. It is always followed by the
        argument name and one or more lines of descriptive text.
        
        E.g. @param filename Name of the source file.
    
    The @keyparam tag
    
        This tag is like the @param tag, but should be used for parameters, that should always
        be given as keyword parameters. It is always followed by the argument name and one 
        or more lines of descriptive text.
        
        E.g. @keyparam extension Optional extension of the source file.
    
    The @return tag
    
        This tag is used to describe a functions or methods return value. It can include one or
        more lines of descriptive text.
        
        E.g. @return list of description strings
    
    The @exception, @throws and @raise tags
    
        These tags are used to describe the exceptions a function or method may raise. It is always
        followed by the exception name and one or more lines of descriptive text.
        
        E.g. @exception ValueError The searched value is not contained in the list.
    
    The @signal tag
    
        This tag is used to describe the signals (PyQt) a class may emit. It is always followed by the
        signal name and one or more lines of descriptive text.
        
        E.g. @signal lastEditorClosed Emitted after the last editor window was closed.
    
    The @deprecated tag
    
        This tag is used to mark a function or method as deprecated. It is always followed by one
        or more lines of descriptive text.
