README for the eric3-doc documentation generator

    eric3-doc is the documentation generator of the eric3 IDE. Python source
    code documentation may be included as ordinary Python doc-strings or as 
    documentation comments. For Quixote Template files (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).
    
    For Ruby files, the documentation string must be started with "=begin edoc"
    and must be ended with "=end". The documentation string for classes, modules
    and functions/methods must follow their defininition.
    
    Documentation for packages (i.e. directories) must be in a file called 
    __init__.py or __init__.rb. If a package directory doesn't contain a file
    like these, documentation for files in this directory is suppressed.
    
    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 understands 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. In order to
    generate a blank line in the output enter a line that contains a single dot
    (.) 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. "<" should be written as "&lt;", ">" as "&gt;", "&" as "&amp;" and
    "@" should be escaped as "@@".
    
    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.
        
        Python 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
            """
            
        Python/Quixote 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
            ###
            
        Ruby Docstring:
            =begin edoc
            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
            =end
    
    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 @event tag
    
        This tag is used to describe the events (PyQt) a class may emit. It is 
        always followed by the event name and one or more lines of descriptive 
        text.
        
        E.g. @event closeEvent Emitted when an editor window is 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.

    The @author tag
    
        This tag is used to name the author of the code.

    The @@ tag
    
        This isn't really a tag. This is used to escape  an at sign at the beginning
        of a line. Everything after the first @ is copied verbatim to the output.
