1EPYDOCGUI(1)                General Commands Manual               EPYDOCGUI(1)
2
3
4

NAME

6       epydocgui - graphical interface to epydoc
7

SYNOPSIS

9       epydocgui [project.prj | modules...]
10
11       epydoc -h
12
13       epydoc -V
14

DESCRIPTION

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
22       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

OPTIONS

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
36       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
43       -h, --help, --usage, -?
44              Display a usage message.
45
46       -V, --version
47              Print the version of Epydoc.
48

HTML FILES

50       The  API  documentation  produced  by  epydoc consists of the following
51       files:
52
53           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
62           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
66           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
71           trees.html
72                  The module and class hierarchies.
73
74           indices.html
75                  The term  and identifier indices.
76
77           help.html
78                  The  help  page  for the project.  This page explains how to
79                  use and navigate the webpage produced by epydoc.
80
81           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
87           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
94           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
102           epydoc.css
103                  The CSS stylesheet used to display all HTML pages.
104
105       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
114       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
119           Bad module name module
120                  Epydoc attempted to import module, but module is not a valid
121                  name for a Python module.
122
123           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
128           Could not import module
129                  Epydoc attempted to import module, but it failed.  This typ‐
130                  ically occurs when module raises an exception.
131
132           file does not exist
133                  Epydoc attempted to import the module contained in file, but
134                  file does not exist.
135
136       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
141           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
146           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
151           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
155           Fields must be the final elements.
156                  The  list  of  fields (@param, etc.)  is not at the end of a
157                  docstring.
158
159           Headings must occur at top level.
160                  The heading is contianed in some other block structure (such
161                  as a list).
162
163           Improper doctest block indentation.
164                  The  doctest  block dedents past the indentation of its ini‐
165                  tial prompt line.
166
167           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
171           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
176           Invalid escape.
177                  An  unknown  escape sequence was used with the inline escape
178                  construction (E{...}).
179
180           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
189           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
195           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
201           Unknown inline markup tag.
202                  An unknown tag was used with the inline markup  construction
203                  ( x{...} ).
204
205           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
211       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
216           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
221           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
228       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
232           @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
237           tag did not expect an argument.
238                  The field tag tag was used with an argument, but it does not
239                  take one.
240
241           tag expected an argument.
242                  The field tag tag was  used  without  an  argument,  but  it
243                  requires one.
244
245           @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
250           @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
255           Unknown field tag tag.
256                  A docstring contains a field with the unknown tag tag.
257
258           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
262       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
267           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
275           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
281           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
292           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
299           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
306           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
313           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

AUTHOR

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

BUGS

326       Report bugs to <edloper@gradient.cis.upenn.edu>.
327

SEE ALSO

329       epydoc(1)
330
331       The epydoc webpage
332              <http://epydoc.sourceforge.net>
333
334       The epytext markup language manual
335              <http://epydoc.sourceforge.net/epytext.html>
336
337
338
339                                                                  EPYDOCGUI(1)
Impressum