1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116
|
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. 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 "<", ">" as ">", "&" as "&" 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.
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.
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.
|