Mercurial Repositories > eric / file comparison

comparison: README-eric6-doc.rst

README-eric6-doc.rst

changeset 4266
17c215c416ba
parent 3758
19866b4e9027
child 4267
94496d77156b
equal deleted inserted replaced
4263:7c7cb5188773 4266:17c215c416ba
1 ================================================
2 README for the eric6-doc documentation generator
3 ================================================
4
5 eric6-doc is the documentation generator of the eric6 IDE. Python source
6 code documentation may be included as ordinary Python doc-strings or as
7 documentation comments. For Quixote Template files (PTL) only documentation
8 comments are available due to the inner workings of Quixote. Documentation
9 comments start with the string ###, followed by the contents and ended by
10 ###. Every line of the documentation comments contents must start with a #
11 (see example below).
12
13 For Ruby files, the documentation string must be started with "=begin edoc"
14 and must be ended with "=end". The documentation string for classes, modules
15 and functions/methods must follow their defininition.
16
17 Documentation for packages (i.e. directories) must be in a file called
18 __init__.py or __init__.rb. If a package directory doesn't contain a file
19 like these, documentation for files in this directory is suppressed.
20
21 The documentation consist of two parts. The first part is the description of
22 the module, class, function or method. The second part, separated from the
23 first by a blank line, consists of one or more tags. These are described below.
24
25 eric6-doc produces HTML files from the documentation found within the source
26 files scaned. It understands the following commandline parameters next to
27 others.
28
29 -o directory
30 Generate files in the named directory.
31
32 -R, -r
33 Perform a recursive search for Python files.
34
35 -x directory
36 Specify a directory basename to be excluded. This option may be repeated
37 multiple times.
38
39 -i
40 Don't generate index files.
41
42 Just type "eric6-doc" to get some usage information.
43
44 1. Description
45 --------------
46 The descriptions are HTML fragments and may contain most standard HTML. The
47 description text is included in the output wrapped in P tags, but unchanged
48 otherwise. Paragraphs have to be separated by a blank line. In order to
49 generate a blank line in the output enter a line that contains a single dot
50 (.). Reserved HTML entities (<, > and &) and the at-sign (@) at the beginning
51 of a line, if that line doesn't contain a tag (see below), must be properly
52 escaped. "<" should be written as "&lt;", ">" as "&gt;", "&" as "&amp;" and
53 "@" should be escaped as "@@".
54
55 The documentation string or documentation comment may contain block tags
56 and inline tags. Inline tags are denoted by curly braces and can be placed
57 anywhere in the main description or in the description part of block tags.
58 Block tags can only be placed in the tag section that follows the main
59 description. Block tags are indicated by an at-sign (@) at the beginning of
60 the line. The text before the first tag is the description of a module, class,
61 method or function.
62
63 Python Docstring::
64
65 """
66 This is sentence one, which gets included as a short description.
67 All additional sentences are included into the full description.
68
69 @param param1 first parameter
70 @exception ValueError list entry wasn't found
71 @return flag indicating success
72 """
73
74 Python/Quixote Documentation comment::
75
76 ###
77 # This is line one, which gets included as a short description.
78 # All additional lines are included into the full description.
79 #
80 # @param param1 first parameter
81 # @exception ValueError list entry wasn't found
82 # @return flag indicating success
83 ###
84
85 Ruby Docstring::
86
87 =begin edoc
88 This is line one, which gets included as a short description.
89 All additional lines are included into the full description.
90
91 @param param1 first parameter
92 @exception ValueError list entry wasn't found
93 @return flag indicating success
94 =end
95
96 2. Block Tags
97 -------------
98 The block tags recogized by eric6-doc are:
99
100 @@
101
102 This isn't really a tag. This is used to escape an at sign at the beginning
103 of a line. Everything after the first @ is copied verbatim to the output.
104
105 @author author
106
107 This tag is used to name the author of the code. For example:
108 @author Detlev Offenbach <detlev@die-offenbachs.de>
109
110 @deprecated description
111
112 This tag is used to mark a function or method as deprecated. It is always
113 followed by one or more lines of descriptive text.
114
115 @event eventname description
116
117 This tag is used to describe the events (PyQt) a class may emit. It is
118 always followed by the event name and one or more lines of descriptive
119 text. For example:
120
121 @event closeEvent Emitted when an editor window is closed.
122
123 @exception exception description
124
125 These tags are used to describe the exceptions a function or method may
126 raise. It is always followed by the exception name and one or more lines
127 of descriptive text. For example:
128
129 @exception ValueError The searched value is not contained in the list.
130
131 @keyparam name description
132
133 This tag is like the @param tag, but should be used for parameters, that
134 should always be given as keyword parameters. It is always followed by
135 the argument name and one or more lines of descriptive text. For example:
136
137 @keyparam extension Optional extension of the source file.
138
139 @param name description
140
141 This tag is used to describe a function or method argument. It is always
142 followed by the argument name and one or more lines of descriptive text.
143 For example:
144
145 @param filename Name of the source file.
146
147 @raise exception description
148
149 This tag is an alias for the @exception tag.
150
151 @return description
152
153 This tag is used to describe a functions or methods return value. It can
154 include one or more lines of descriptive text. For example:
155
156 @return list of description strings
157
158 @see reference
159
160 This tag is used to include a reference in the documentation. It comes in
161 three different forms.
162
163 @see "string"
164
165 Adds a text entry of string. No link is generated. eric6-doc distinguishes
166 this form from the others by looking for a double-quote (") as the first
167 character. For example:
168
169 @see "eric6-doc readme file"
170
171 @see <a href="URL#value">label</a>
172
173 Adds a link as defined by URL#value. eric6-doc distinguishes this form from
174 the others by looking for a less-than symbol (<) as the first character.
175 For example:
176
177 @see <a href="eric6.eric6-doc.html>eric6-doc documentation generator</a>
178
179 @see package.module#member label
180
181 Adds a link to "member" in "module" in "package". package can be a package
182 path, where the package names are separated by a dot character (.). The
183 "package.module#member" part must not be split over several lines and
184 must name a valid target within the documentation directory. For example:
185
186 @see eric6.eric6-doc#main eric6-doc main() function
187 @see eric6.DocumentationTools.ModuleDocumentor#ModuleDocument.__genModuleSection
188 ModuleDocument.__genModuleSection
189
190 @signal signalname description
191
192 This tag is used to describe the signals (PyQt) a class may emit. It is
193 always followed by the signal name and one or more lines of descriptive
194 text. For example:
195
196 @signal lastEditorClosed Emitted after the last editor window was
197 closed.
198
199 @throws exception description
200
201 This tag is an alias for the @exception tag.
202
203 3. Inline Tags
204 --------------
205 The inline tags recogized by eric6-doc are:
206
207 {@link package.module#member label}
208
209 Inserts an in-line link with visible text label that points to the documentation
210 given in the reference. This tag works he same way as the @see block tag of this
211 form.

Mercurial Repository: eric

eric ide

mercurial