1
README for the eric4-doc documentation generator
3
eric4-doc is the documentation generator of the eric4 IDE. Python source
4
code documentation may be included as ordinary Python doc-strings or as
5
documentation comments. For Quixote Template files (PTL) only documentation
6
comments are available due to the inner workings of Quixote. Documentation
7
comments start with the string ###, followed by the contents and ended by
8
###. Every line of the documentation comments contents must start with a #
11
For Ruby files, the documentation string must be started with "=begin edoc"
12
and must be ended with "=end". The documentation string for classes, modules
13
and functions/methods must follow their defininition.
15
Documentation for packages (i.e. directories) must be in a file called
16
__init__.py or __init__.rb. If a package directory doesn't contain a file
17
like these, documentation for files in this directory is suppressed.
19
The documentation consist of two parts. The first part is the description of
20
the module, class, function or method. The second part, separated from the
21
first by a blank line, consists of one or more tags. These are described below.
23
eric4-doc produces HTML files from the documentation found within the source
24
files scaned. It understands the following commandline parameters next to others.
27
Generate files in the named directory.
30
Perform a recursive search for Python files.
33
Specify a directory basename to be excluded. This option may be repeated
37
Don't generate index files.
39
Just type "eric4-doc" to get some usage information.
43
The descriptions are HTML fragments and may contain most standard HTML. The
44
description text is included in the output wrapped in P tags, but unchanged
45
otherwise. Paragraphs have to be separated by a blank line. In order to
46
generate a blank line in the output enter a line that contains a single dot
47
(.). Reserved HTML entities (<, > and &) and the at-sign (@) at the beginning
48
of a line, if that line doesn't contain a tag (see below), must be properly
49
escaped. "<" should be written as "<", ">" as ">", "&" as "&" and
50
"@" should be escaped as "@@".
52
The documentation string or documentation comment may contain block tags
53
and inline tags. Inline tags are denoted by curly braces and can be placed
54
anywhere in the main description or in the description part of block tags.
55
Block tags can only be placed in the tag section that follows the main
56
description. Block tags are indicated by an at-sign (@) at the beginning of
57
the line. The text before the first tag is the description of a module, class,
62
This is sentence one, which gets included as a short description.
63
All additional sentences are included into the full description.
65
@param param1 first parameter
66
@exception ValueError list entry wasn't found
67
@return flag indicating success
70
Python/Quixote Documentation comment:
72
# This is line one, which gets included as a short description.
73
# All additional lines are included into the full description.
75
# @param param1 first parameter
76
# @exception ValueError list entry wasn't found
77
# @return flag indicating success
82
This is line one, which gets included as a short description.
83
All additional lines are included into the full description.
85
@param param1 first parameter
86
@exception ValueError list entry wasn't found
87
@return flag indicating success
92
The block tags recogized by eric4-doc are:
95
This isn't really a tag. This is used to escape an at sign at the beginning
96
of a line. Everything after the first @ is copied verbatim to the output.
99
This tag is used to name the author of the code. For example:
100
@author Detlev Offenbach <detlev@die-offenbachs.de>
102
@deprecated description
103
This tag is used to mark a function or method as deprecated. It is always
104
followed by one or more lines of descriptive text.
106
@event eventname description
107
This tag is used to describe the events (PyQt) a class may emit. It is
108
always followed by the event name and one or more lines of descriptive
111
@event closeEvent Emitted when an editor window is closed.
113
@exception exception description
114
These tags are used to describe the exceptions a function or method may
115
raise. It is always followed by the exception name and one or more lines
116
of descriptive text. For example:
118
@exception ValueError The searched value is not contained in the list.
120
@keyparam name description
121
This tag is like the @param tag, but should be used for parameters, that
122
should always be given as keyword parameters. It is always followed by
123
the argument name and one or more lines of descriptive text. For example:
125
@keyparam extension Optional extension of the source file.
127
@param name description
128
This tag is used to describe a function or method argument. It is always
129
followed by the argument name and one or more lines of descriptive text.
132
@param filename Name of the source file.
134
@raise exception description
135
This tag is an alias for the @exception tag.
138
This tag is used to describe a functions or methods return value. It can
139
include one or more lines of descriptive text. For example:
141
@return list of description strings
144
This tag is used to include a reference in the documentation. It comes in
145
three different forms.
148
Adds a text entry of string. No link is generated. eric4-doc distinguishes
149
this form from the others by looking for a double-quote (") as the first
150
character. For example:
152
@see "eric4-doc readme file"
154
@see <a href="URL#value">label</a>
155
Adds a link as defined by URL#value. eric4-doc distinguishes this form from
156
the others by looking for a less-than symbol (<) as the first character.
159
@see <a href="eric4.eric4-doc.html>eric4-doc documentation generator</a>
161
@see package.module#member label
162
Adds a link to "member" in "module" in "package". package can be a package
163
path, where the package names are separated by a dot character (.). The
164
"package.module#member" part must not be split over several lines and
165
must name a valid target within the documentation directory. For example:
167
@see eric4.eric4-doc#main eric4-doc main() function
168
@see eric4.DocumentationTools.ModuleDocumentor#ModuleDocument.__genModuleSection
169
ModuleDocument.__genModuleSection
171
@signal signalname description
172
This tag is used to describe the signals (PyQt) a class may emit. It is
173
always followed by the signal name and one or more lines of descriptive
176
@signal lastEditorClosed Emitted after the last editor window was
179
@throws exception description
180
This tag is an alias for the @exception tag.
184
The inline tags recogized by eric4-doc are:
186
{@link package.module#member label}
187
Inserts an in-line link with visible text label that points to the documentation
188
given in the reference. This tag works he same way as the @see block tag of this
added
removed
eric/README-eric4-doc.txt
