1EPYDOCGUI(1) General Commands Manual EPYDOCGUI(1)
2
6 epydocgui - graphical interface to epydoc
7
9 epydocgui [project.prj | modules...]
10 epydoc -h
12 epydoc -V
14
16 epydocgui is a graphical interface to epydoc, which generates API docu‐
17 mentation for Python modules and packages, based on their docstrings.
18 A lightweight markup language called epytext can be used to format doc‐
19 strings, and to add information about specific fields, such as parame‐
20 ters and instance variables.
21 The API documentation produced by epydocgui consists of a set of HTML
23 files. Two subdirectories are created for the public and private docu‐
24 mentation. Within each subdirectories, every class and module is docu‐
25 mented in its own file. An index file, a trees file, and a help file
26 are also created. If you select the frames option, then a frames-based
27 table of contents is also produced.
28
30 project.prj
31 The name of a project file that was saved with epydocgui.
32 Project files record a list of related modules, and the options
33 that should be used to generate the documentation for those mod‐
34 ules.
35 modules...
37 The list of the modules that should be documented. Modules can
38 be specified using module names (such as os.path), filenames
39 (such as epydoc/epytext.py), or directory names (such as epy‐
40 doc/). Directory names specify packages, and are expanded to
41 include all sub-modules and sub-packages.
42 -h, --help, --usage, -?
44 Display a usage message.
45 -V, --version
47 Print the version of Epydoc.
48
50 The API documentation produced by epydoc consists of the following
51 files:
52 index.html
54 The standard entry point for the documentation. Normally,
55 index.html is a frame index file, which defines three
56 frames: two frames on the left side of the browser contain a
57 table of contents, and the main frame on the right side of
58 the window contains documentation pages. But if the
59 --no-frames option is used, then index.html will redirect
60 the user to the project's top page.
61 m-module.html
63 The API documentation for a module. module is the complete
64 dotted name of the module, such as sys or epydoc.epytext.
65 c-class.html
67 The API documentation for a class, exception, or type.
68 class is the complete dotted name of the class, such as epy‐
69 doc.epytext.Token or array.ArrayType.
70 trees.html
72 The module and class hierarchies.
73 indices.html
75 The term and identifier indices.
76 help.html
78 The help page for the project. This page explains how to
79 use and navigate the webpage produced by epydoc.
80 toc.html
82 The top-level table of contents page. This page is dis‐
83 played in the upper-left frame, and provides links to
84 toc-everything.html and the toc-m-module.html files.
85 toc.html is not generated if the --no-frames option is used.
86 toc-everything.html
88 The table of contents for the entire project. This page is
89 displayed in the lower-left frame, and provides links to
90 every class, type, exception, function, and variable defined
91 by the project. toc-everything.html is not generated if the
92 --no-frames option is used.
93 toc-m-module.html
95 The table of contents for a module. This page is displayed
96 in the lower-left frame, and provides links to every class,
97 type, exception, function, and variable defined by the mod‐
98 ule. module is the complete dotted name of the module, such
99 as sys or epydoc.epytext. toc-m-module.html is not gener‐
100 ated if the --no-frames option is used.
101 epydoc.css
103 The CSS stylesheet used to display all HTML pages.
104 By default, epydoc creates two subdirectories in the output directory:
106 public and private. Each directory contains all of the files specified
107 above. But if the --no-private option is used, then no subdirectories
108 are created, and the public documentation is written directly to the
109 output directory. ivided into five categories: import errors; epytext
110 errors; epytext warnings; field warnings; and inspection errors. When‐
111 ver epydoc encounters an error, it issues a warning message that
112 describes the error, and attempts to continue generating documentation.
113 Import errors indicate that epydoc was unable to import a module.
115 Import errors typically prevent epydoc from generating documentation
116 for the module in question. Epydoc can generate the following import
117 errors:
118 Bad module name module
120 Epydoc attempted to import module, but module is not a valid
121 name for a Python module.
122 Could not find a UID for link-target
124 Epydoc was unable to find the object referred to by an
125 inline link construction (L{...}). This is usually caused
126 by a typo in the link.
127 Could not import module
129 Epydoc attempted to import module, but it failed. This typ‐
130 ically occurs when module raises an exception.
131 file does not exist
133 Epydoc attempted to import the module contained in file, but
134 file does not exist.
135 Epytext errors are caused by epytext docstrings that contain invalid
137 markup. Whenever an epytext error is detected, the docstring in ques‐
138 tion is treated as a plaintext docstring. Epydoc can generate the fol‐
139 lowing epytext errors:
140 Bad link target.
142 The target specified for an inline link contruction (L{...})
143 is not well-formed. Link targets must be valid python iden‐
144 tifiers.
145 Bad uri target.
147 The target specified for an inline uri contruction (U{...})
148 is not well-formed. This typically occurs if inline markup
149 is nested inside the URI target.
150 Fields must be at the top level.
152 The list of fields (@param, etc.) is contained by some
153 other block structure (such as a list or a section).
154 Fields must be the final elements.
156 The list of fields (@param, etc.) is not at the end of a
157 docstring.
158 Headings must occur at top level.
160 The heading is contianed in some other block structure (such
161 as a list).
162 Improper doctest block indentation.
164 The doctest block dedents past the indentation of its ini‐
165 tial prompt line.
166 Improper heading indentation.
168 The heading for a section is not left-aligned with the para‐
169 graphs in the section that contains it.
170 Improper paragraph indentation.
172 The paragraphs within a block are not left-aligned. This
173 error is often generated when plaintext docstrings are
174 parsed using epytext.
175 Invalid escape.
177 An unknown escape sequence was used with the inline escape
178 construction (E{...}).
179 Lists must be indented.
181 An unindented line immediately following a paragraph starts
182 with a list bullet. Epydoc is not sure whether you meant to
183 start a new list item, or meant for a paragraph to include a
184 word that looks like a bullet. If you intended the former,
185 then indent the list. If you intended the latter, then
186 change the word-wrapping of the paragraph, or escape the
187 first character of the word that looks like a bullet.
188 Unbalanced '{'.
190 The docstring contains unbalanced braces. Epytext requires
191 that all braces must be balanced. To include a single
192 unbalanced brace, use the escape sequences E{lb} (left
193 brace) and E{rb} (right brace).
194 Unbalanced '}'.
196 The docstring contains unbalanced braces. Epytext requires
197 that all braces must be balanced. To include a single
198 unbalanced brace, use the escape sequences E{lb} (left
199 brace) and E{rb} (right brace).
200 Unknown inline markup tag.
202 An unknown tag was used with the inline markup construction
203 ( x{...} ).
204 Wrong underline character for heading.
206 The underline character used for this section heading does
207 not indicate an appopriate section level. The "=" character
208 should be used to underline sections; "-" for subsections;
209 and "~" for subsubsections.
210 Epytext warnings are caused by epytext docstrings that contain ques‐
212 tionable or suspicious markup. Epytext warnings do not prevent the
213 docstring in question from being parsed. Epydoc can generate the fol‐
214 lowing epytext warnings:
215 Possible mal-formatted field item.
217 Epytext detected a line that looks like a field item, but is
218 not correctly formatted. This typically occurs when the
219 trailing colon (":") is not included in the field tag.
220 Possible heading typo.
222 Epytext detected a pair of lines that looks like a heading,
223 but the number of underline characters does not match the
224 number of characters in the heading. The number of charac‐
225 ters in these two lines must match exactly for them to be
226 considered a heading.
227 Field warnings are caused by epytext docstrings containing invalid
229 fields. The contents of the invalid field are generally ignored. Epy‐
230 doc can generate the following field warnings:
231 @param for unknown parameter param.
233 A @param field was used to specify the type for a parameter
234 that is not included in the function's signature. This is
235 typically caused by a typo in the parameter name.
236 tag did not expect an argument.
238 The field tag tag was used with an argument, but it does not
239 take one.
240 tag expected an argument.
242 The field tag tag was used without an argument, but it
243 requires one.
244 @type for unknown parameter param.
246 A @type field was used to specify the type for a parameter
247 that is not included in the function's signature. This is
248 typically caused by a typo in the parameter name.
249 @type for unknown variable var.
251 A @type field was used to specify the type for a variable,
252 but no other information is known about the variable. This
253 is typically caused by a typo in the variable name.
254 Unknown field tag tag.
256 A docstring contains a field with the unknown tag tag.
257 Redefinition of field.
259 Multiple field tags define the value of field in the same
260 docstring, but field can only take a single value.
261 Inspection errors are generated if epydoc encounters problems while
263 attempting to inspect the properties of a documented object. Most of
264 inspection errors do not prevent epydoc from documenting the object in
265 question. Epydoc can generate the following inspection errors:
266 The parameters of inhmethod do not match basemethod.
268 The parameters of the undocumented method inhmethod do not
269 match the parameters of the base class method basemethod
270 that it overrides. As a result, inhmethod does not inherit
271 documentation from basemethod. If the difference in parame‐
272 ters is intentional, then you can eliminate the warning by
273 adding a (possibly empty) docstring to inhmethod.
274 Docmap cannot add a type
276 Epydoc attempted to document an object with an unknown type.
277 This error is typically generated by packages and modules
278 that manipulate the import mechanism, such that importing a
279 module produces some other type of object.
280 UID conflict detected: uid
282 Two different objects were assigned the same unique identi‐
283 fier by epydoc. This can cause epydoc to substitute the
284 documentation of one object with the documentation of
285 another object that is assigned the same unique identifier.
286 However, this will usually only cause problems if the two
287 objects with the same unique identifiers are both modules or
288 classes, in which case the API documentation page for one
289 object will overwrite the API documentation page for the
290 other object.
291 object appears in multiple builtin modules
293 While attempting to determine which module defines the
294 builtin object object, epydoc encountered multiple candi‐
295 dates, and was unable to decide which candidate was correct.
296 In this case, epydoc arbitrarily chooses the first candidate
297 that it finds.
298 object appears in multiple .py modules
300 While attempting to determine which module defines the
301 builtin object object, epydoc encountered multiple candi‐
302 dates, and was unable to decide which candidate was correct.
303 In this case, epydoc arbitrarily chooses the first candidate
304 that it finds.
305 object appears in multiple .so modules
307 While attempting to determine which module defines the
308 builtin object object, epydoc encountered multiple candi‐
309 dates, and was unable to decide which candidate was correct.
310 In this case, epydoc arbitrarily chooses the first candidate
311 that it finds.
312 Could not find a module for object
314 Epydoc was unable to determine which module defines object.
315 If object is a function, then this will prevent epydoc from
316 generating any documentation for object, since it does not
317 know what page to put the documentation on. Otherwise, this
318 will prevent the documentation for object from including a
319 link to its containing module.
320
322 Epydoc was written by Edward Loper. This man page was originally writ‐
323 ten by Moshe Zadka, and is currently maintained by Edward Loper.
324
326 Report bugs to <edloper@gradient.cis.upenn.edu>.
327
329 epydoc(1)
330 The epydoc webpage
332 <http://epydoc.sourceforge.net>
333 The epytext markup language manual
335 <http://epydoc.sourceforge.net/epytext.html>
336 EPYDOCGUI(1)