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

NAME

6       epydoc - generate API documentation from Python docstrings
7

SYNOPSIS

9       epydoc [action] [options] names...
10

DESCRIPTION

12       epydoc  generates  API  documentation  for Python modules and packages,
13       based on their docstrings.  A lightweight markup language  called  epy‐
14       text  can  be  used  to format docstrings, and to add information about
15       specific fields, such as parameters  and  instance  variables.   Epydoc
16       also  understands  docstrings written in ReStructuredText, Javadoc, and
17       plaintext.  Currently, epydoc supports two basic output  formats:  HTML
18       and LaTeX.
19
20       The HTML API documentation produced by epydoc consists of a set of HTML
21       files, including: an API documentation page for each class and  module;
22       a  syntax-highlighted  source  code page for each module; an identifier
23       index page; a help page; and a frames-based table  of  contents.   When
24       appropriate,  epydoc  will  also generate index pages for bugs, defined
25       terms, and to-do items; a class hierarchy page; and a package hierarchy
26       page.
27
28       The LaTeX API documentation produced by epydoc consists of a main LaTeX
29       file, and a LaTeX file for each module.  If you  use  --dvi,  --ps,  or
30       --pdf  , then epydoc will invoke external commands to convert the LaTeX
31       output to the requested format.  Note that the LaTeX  files  containing
32       the documentation for individual modules can be included as chapters or
33       sections of other LaTeX documents, using the  LaTeX  \include  command.
34       If  you  wish  to  include individual classes in other LaTeX documents,
35       then use the --separate-classes option to produce a separate LaTeX file
36       for each class.
37
38       epydoc can also be used to check the completeness of the API documenta‐
39       tion.  By default, it checks that every public package, module,  class,
40       method,  and  function has a docstring description.  The --tests option
41       can be used to specify additional tests to perform.
42

OPTIONS

44       Epydoc's options  are  divided  into  six  categories:  basic  options,
45       actions,  generation options, output options, graph options, and return
46       value options.
47
48       BASIC OPTIONS
49
50           names...
51                  The list of objects that should be documented.  Objects  can
52                  be  specified  using  Python dotted names (such as os.path),
53                  filenames (such as epydoc/epytext.py),  or  directory  names
54                  (such  as  epydoc/).   Directory names specify packages, and
55                  are expanded to include all  sub-modules  and  sub-packages.
56                  If  you wish to exclude certain sub-modules or sub-packages,
57                  use the --exclude option (described below).
58
59           --config file
60                  A  configuration   file,   specifying   additional   option‐
61                  sand/ornames.  This option may be repeated.
62
63           --q, --quiet, --v, --verbose
64                  Produce  quite (or verbose) output.  If used multiple times,
65                  this option produces successively more  quiet  (or  verbose)
66                  output.
67
68           --debug
69                  Show full tracebacks for internal errors.
70
71           --simple-term
72                  Do  not  try  to use color or cursor control when displaying
73                  the progress bar, warnings, or errors.
74
75       ACTIONS
76
77           --html    Write HTML output.  [default]
78
79           --latex   Write LaTeX output.
80
81           --dvi     Write DVI output.
82
83           --ps      Write Postscript output.
84
85           --pdf     Write Adobe Acrobat (pdf) output.
86
87           --check   Perform completeness checks on the documentation.
88
89           --pickle  Write the documentation to a pickle file.
90
91       GENERATION OPTIONS
92
93           --docformat format
94                  Set the default value for __docformat__ to  format.   __doc‐
95                  format__ is a module variable that specifies the markup lan‐
96                  guage for the docstrings in a module.  Its value consists of
97                  the name of a markup language, optionally followed by a lan‐
98                  guage code (such as en for English).   For  a  list  of  the
99                  markup  languages currently recognized by epydoc, run epydoc
100                  --help docformat.
101
102           --parse-only
103                  Gather all information about the documented objects by pars‐
104                  ing  the  relevant Python source code; in particular, do not
105                  use introspection to gather information about the documented
106                  objects.   This  option should be used when epydoc is run on
107                  untrusted code; or on code  that  can  not  be  introspected
108                  because  of  missing  dependencies,  or because importing it
109                  would cause undesired side-effects.
110
111           --introspect-only
112                  Gather all  information  about  the  documented  objects  by
113                  introspection;  in  particular, do not gather information by
114                  parsing the object's Python source code.
115
116           --exclude PATTERN
117                  Do not document any object whose name matches the given reg‐
118                  ular expression pattern.
119
120           --exclude-introspect PATTERN
121                  Do  not  use  introspection  to gather information about any
122                  object whose name matches the given regular expression.
123
124           --exclude-parse PATTERN
125                  Do not use Python source code parsing to gather  information
126                  about  any  object  whose  name  matches  the  given regular
127                  expression.
128
129           --inheritance format
130                  The format that should be used to display inherited methods,
131                  variables, and properties in the generated "summary" tables.
132                  If format is "grouped," then inherited objects are  gathered
133                  into  groups,  based  on which class that they are inherited
134                  from.  If format is "listed,"  then  inherited  objects  are
135                  listed  in a short list at the end of the summary table.  If
136                  format is "included," then inherited objects  are  mixed  in
137                  with  non-inherited  objects.   The  default format for HTML
138                  output is "grouped."
139
140           --show-private, --no-private
141                  These options control whether documentation is generated for
142                  private  objects.   By  default, the generated documentation
143                  includes private objects, and users can  choose  whether  to
144                  view  private  objects or not, by clicking on "show private"
145                  and "hide private" links.  But if  you  want  to  discourage
146                  users  from directly accessing private objects, then you may
147                  prefer not to generate documentation for private objects.
148
149           --show-imports, --no-imports
150                  These options control whether module imports are included in
151                  the  generated  documentation.   By default, imports are not
152                  included.
153
154           --show-sourcecode, --no-sourcecode
155                  These options control whether or not epydoc should  generate
156                  syntax-highlighted  pages  containing the souce code of each
157                  module in the HTML output.  By default, the sourcecode pages
158                  are generated.
159
160           --include-log
161                  Generate  an  HTML page epydoc-log.html containing all error
162                  and warning messages  that  are  generated  by  epydoc,  and
163                  include it in the generated output.
164
165       OUTPUT OPTIONS
166
167           -o dir, --output dir
168                  The  output  directory.  If dir does not exist, then it will
169                  be created.  If no output directory is specified,  then  the
170                  action name (e.g., html or pdf).  html
171
172           -c sheet, --css sheet
173                  CSS  stylesheet  for HTML output files.  If sheet is a file,
174                  then the stylesheet is copied  from  that  file;  otherwise,
175                  sheet is taken to be the name of a built-in stylesheet.  For
176                  a list of the built-in stylesheets, run epydoc  --help  css.
177                  If  a  CSS  stylesheet  is  not  specified, then the default
178                  stylesheet is used.
179
180           -n name, --name name
181                  The name of the project whose documentation is being  gener‐
182                  ated.
183
184           -u url, --url url
185                  The URL of the project's homepage.
186
187
188           --navlink html
189                  HTML code for the homepage link on the HTML navi‐
190                  gation bar.   If  this  HTML  code  contains  any
191                  hyperlinks   (<a  href=...>),  then  it  will  be
192                  inserted verbatim.  If it does  not  contain  any
193                  hyperlinks,  and a project url is specified (with
194                  --url), then a hyperlink to the specified URL  is
195                  added to the link.
196
197           --help-file file
198                  An  alternate help file.  file should contain the
199                  body of an HTML file -- navigation bars  will  be
200                  added to it.
201
202           --show-frames, --no-frames
203                  These  options  control  whether HMTL output will
204                  include a frames-base table of contents page.  By
205                  default,  the  frames-based  table of contents is
206                  included.
207
208           --separate-classes
209                  In the LaTeX output, describe  each  class  in  a
210                  separate section of the documentation, instead of
211                  including them in  the  documentation  for  their
212                  modules.   This creates a separate LaTeX file for
213                  each class, so it can also be useful if you  want
214                  to  include  the  documentation  for  one  or two
215                  classes as sections of your own LaTeX document.
216
217           --include-timestamp
218                  Include a timestamp in the generated output.
219
220           --suppress-timestamp
221                  ignored, only exists for backwards compatibility.
222                  (it is now the default)
223
224       GRAPH OPTIONS
225
226           --graph graphtype
227                  Include graphs of type graphtype in the generated
228                  output.  Graphs are generated using the  Graphviz
229                  dot executable.  If this executable is not on the
230                  path, then use --dotpath to specify its location.
231                  This  option  may be repeated to include multiple
232                  graph types in the output.  graphtype  should  be
233                  one   of:  all,  classtree,  callgraph,  or  uml‐
234                  classtree.
235
236           --dotpath path
237                  The path to the Graphviz dot executable.
238
239           --graph-font font
240                  The name of the font used  to  generate  Graphviz
241                  graphs.  (e.g., helvetica or times).
242
243           --graph-font-size size
244                  The  size  of  the font used to generate Graphviz
245                  graphs, in points.
246
247           --pstat file
248                  A pstat output file, to  be  used  in  generating
249                  call graphs.
250
251       RETURN VALUE OPTIONS
252
253           --fail-on-error
254                  Return  a  non-zero exit status, indicating fail‐
255                  ure, if any errors are encountered.
256
257           --fail-on-warning
258                  Return a non-zero exit status,  indicating  fail‐
259                  ure,  if  any  errors or warnings are encountered
260                  (not including docstring warnings).
261
262           --fail-on-docstring-warning
263                  Return a non-zero exit status,  indicating  fail‐
264                  ure,  if  any  errors or warnings are encountered
265                  (including docstring warnings).
266

HTML FILES

268       The HTML API documentation produced by  epydoc  consists  of
269       the following files:
270
271       OBJECT DOCUMENTATION PAGES
272
273           index.html
274                  The  standard  entry point for the documentation.
275                  Normally, index.html is a copy of the frames file
276                  (frames.html).   But if the --no-frames option is
277                  used, then index.html is a copy of the API  docu‐
278                  mentation  home page, which is normally the docu‐
279                  mentation page for the top-level package or  mod‐
280                  ule  (or  the trees page if there is no top-level
281                  package or module).
282
283           module-module.html
284                  The API documentation for a  module.   module  is
285                  the  complete  dotted name of the module, such as
286                  sys or epydoc.epytext.
287
288           class-class.html
289                  The API documentation for a class, exception,  or
290                  type.   class  is the complete dotted name of the
291                  class,   such    as    epydoc.epytext.Token    or
292                  array.ArrayType.
293
294           module-pysrc.html
295                  A  syntax-highlighted  page containing the Python
296                  source code for module.  This page includes links
297                  back to the API documentation pages.
298
299           module-tree.html
300                  The module hierarchy.
301
302           class-tree.html
303                  The class hierarchy.  This page is only generated
304                  if at least one class is documented.
305
306       INDICES
307
308           identifier-index.html
309                  An index of all documented identifiers.   If  the
310                  identifier   index   contains   more  than  3,000
311                  entries, then it  will  be  split  into  separate
312                  pages  for  each  letter, named identifier-index-
313                  a.html, identifier-index-b.html, etc.
314
315           term-index.html
316                  An index of all  explicitly  marked  definitional
317                  terms.   This  page is only generated if at least
318                  one definition term is marked in a formatted doc‐
319                  string.
320
321           bug-index.html
322                  An  index  of  all explicitly marked @bug fields.
323                  This page is only generated if at least one  @bug
324                  field is listed in a formatted docstring.
325
326           todo-index.html
327                  An  index  of all explicitly marked @todo fields.
328                  This page is only generated if at least one @todo
329                  field is listed in a formatted docstring.
330
331           changed-index.html
332                  An   index  of  all  explicitly  marked  @changed
333                  fields.  This page is only generated if at  least
334                  one  @changed field is listed in a formatted doc‐
335                  string.
336
337           deprecated-index.html
338                  An index of  all  explicitly  marked  @deprecated
339                  fields.   This page is only generated if at least
340                  one @deprecated field is listed  in  a  formatted
341                  docstring.
342
343           since-index.html
344                  An  index of all explicitly marked @since fields.
345                  This page is  only  generated  if  at  least  one
346                  @since field is listed in a formatted docstring.
347
348       FRAMES-BASED TABLE OF CONTENTS
349
350           frames.html
351                  The  main  frames  file.   Two frames on the left
352                  side of the window contain a table  of  contents,
353                  and  the main frame on the right side of the win‐
354                  dow contains API documentation pages.
355
356           toc.html
357                  The top-level table of contents page.  This  page
358                  is   displayed   in   the   upper-left  frame  of
359                  frames.html, and provides links to the toc-every‐
360                  thing.html and toc-module-module.html pages.
361
362           toc-everything.html
363                  The  table  of  contents  for the entire project.
364                  This page is displayed in the lower-left frame of
365                  frames.html,  and  provides links to every class,
366                  type, exception, function, and  variable  defined
367                  by the project.
368
369           toc-module-module.html
370                  The table of contents for a module.  This page is
371                  displayed in the lower-left frame of frames.html,
372                  and  provides  links to every class, type, excep‐
373                  tion, function, and variable defined by the  mod‐
374                  ule.   module  is the complete dotted name of the
375                  module, such as sys or epydoc.epytext.
376
377       OTHER PAGES
378
379           help.html
380                  The  help  page  for  the  project.   This   page
381                  explains how to use and navigate the webpage pro‐
382                  duced by epydoc.
383
384           redirect.html
385                  This page uses  javascript  to  translate  dotted
386                  names  to their corresponding URLs.  For example,
387                  in epydoc's documentation, loading the page  <re‐
388                  direct.html#epydoc.apidoc.DottedName>  will auto‐
389                  matically redirect the browser to <epydoc.apidoc-
390                  module.html#DottedName>.
391
392           epydoc.css
393                  The  CSS  stylesheet  used  to  display  all HTML
394                  pages.
395
396           epydoc.js
397                  A javascript file used to define javascript func‐
398                  tions used by epydoc.
399
400           epydoc-log.html
401                  A  page  containing  a  log  of  all warnings and
402                  errors that were generated by epydoc, along  with
403                  a  table  listing  all  of  the options that were
404                  used.
405

LATEX FILES

407       The LaTeX API documentation produced by epydoc  consists  of
408       the following files:
409
410           api.pdf
411                  An  Adobe  Acrobat (pdf) file containing the com‐
412                  plete API documentation.  This file is only  gen‐
413                  erated if you use the --pdf option.
414
415           api.tex
416                  The  top-level LaTeX file.  This file imports the
417                  other LaTeX files, to  create  a  single  unified
418                  document.
419
420           api.dvi
421                  A dvi file containing the complete API documenta‐
422                  tion.  This file is only generated if you use the
423                  --dvi  option,  the  --ps  option,  or  the --pdf
424                  option.
425
426           api.ps A postscript file  containing  the  complete  API
427                  documentation.   This  file  is only generated if
428                  you use the --ps option or the --pdf option.
429
430           module-module.tex
431                  The API documentation for a  module.   module  is
432                  the  complete  dotted name of the module, such as
433                  sys or epydoc.epytext.
434
435           class-class.tex
436                  The API documentation for a class, exception,  or
437                  type.   class  is the complete dotted name of the
438                  class,   such    as    epydoc.epytext.Token    or
439                  array.ArrayType.  These class documentation files
440                  are only created if the --separate-classes option
441                  is  used;  otherwise,  the documentation for each
442                  class is included in its  module's  documentation
443                  file.
444

DIAGNOSTICS

446       EPYTEXT MARKUP WARNING MESSAGES
447           Epytext  errors  are  caused  by epytext docstrings that
448           contain invalid markup.  Whenever an  epytext  error  is
449           detected,  the  docstring  in  question  is treated as a
450           plaintext docstring.  Epydoc can generate the  following
451           epytext errors:
452
453           Bad link target.
454                  The  target specified for an inline link contruc‐
455                  tion (L{...}) is not well-formed.   Link  targets
456                  must be valid python identifiers.
457
458           Bad uri target.
459                  The  target  specified for an inline uri contruc‐
460                  tion (U{...}) is not well-formed.  This typically
461                  occurs  if inline markup is nested inside the URI
462                  target.
463
464           Fields must be at the top level.
465                  The list of fields (@param, etc.)   is  contained
466                  by  some other block structure (such as a list or
467                  a section).
468
469           Fields must be the final elements.
470                  The list of fields (@param, etc.)  is not at  the
471                  end of a docstring.
472
473           Headings must occur at top level.
474                  The  heading  is  contianed  in  some other block
475                  structure (such as a list).
476
477           Improper doctest block indentation.
478                  The doctest block dedents past the indentation of
479                  its initial prompt line.
480
481           Improper heading indentation.
482                  The  heading  for  a  section is not left-aligned
483                  with the paragraphs in the section that  contains
484                  it.
485
486           Improper paragraph indentation.
487                  The  paragraphs  within  a  block  are  not left-
488                  aligned.  This  error  is  often  generated  when
489                  plaintext docstrings are parsed using epytext.
490
491           Invalid escape.
492                  An  unknown  escape  sequence  was  used with the
493                  inline escape construction (E{...}).
494
495           Lists must be indented.
496                  An unindented line immediately following a  para‐
497                  graph  starts  with a list bullet.  Epydoc is not
498                  sure whether you meant to start a new list  item,
499                  or  meant  for a paragraph to include a word that
500                  looks like a bullet.  If you intended the former,
501                  then  indent  the list.  If you intended the lat‐
502                  ter, then change the word-wrapping of  the  para‐
503                  graph,  or escape the first character of the word
504                  that looks like a bullet.
505
506           Unbalanced '{'.
507                  The docstring contains unbalanced  braces.   Epy‐
508                  text  requires  that all braces must be balanced.
509                  To include a single  unbalanced  brace,  use  the
510                  escape  sequences  E{lb}  (left  brace) and E{rb}
511                  (right brace).
512
513           Unbalanced '}'.
514                  The docstring contains unbalanced  braces.   Epy‐
515                  text  requires  that all braces must be balanced.
516                  To include a single  unbalanced  brace,  use  the
517                  escape  sequences  E{lb}  (left  brace) and E{rb}
518                  (right brace).
519
520           Unknown inline markup tag.
521                  An unknown tag was used with  the  inline  markup
522                  construction ( x{...} ).
523
524           Wrong underline character for heading.
525                  The  underline  character  used  for this section
526                  heading does not indicate an  appopriate  section
527                  level.   The  "="  character  should  be  used to
528                  underline sections; "-" for subsections; and  "~"
529                  for subsubsections.
530
531           Possible mal-formatted field item.
532                  Epytext  detected  a line that looks like a field
533                  item, but is not correctly formatted.  This typi‐
534                  cally occurs when the trailing colon (":") is not
535                  included in the field tag.
536
537           Possible heading typo.
538                  Epytext detected a pair of lines that looks  like
539                  a heading, but the number of underline characters
540                  does not match the number of  characters  in  the
541                  heading.   The  number of characters in these two
542                  lines must match exactly for them to  be  consid‐
543                  ered a heading.
544
545       FIELD WARNINGS
546           Field  warnings  are  caused  by  docstrings  containing
547           invalid fields.  The contents of the invalid  field  are
548           generally  ignored.   Epydoc  can generate the following
549           field warnings:
550
551           @param for unknown parameter param.
552                  A @param field was used to specify the type for a
553                  parameter  that is not included in the function's
554                  signature.  This is typically caused by a typo in
555                  the parameter name.
556
557           tag did not expect an argument.
558                  The  field tag tag was used with an argument, but
559                  it does not take one.
560
561           tag expected an argument.
562                  The field tag tag was used without  an  argument,
563                  but it requires one.
564
565           @type for unknown parameter param.
566                  A  @type field was used to specify the type for a
567                  parameter that is not included in the  function's
568                  signature.  This is typically caused by a typo in
569                  the parameter name.
570
571           @type for unknown variable var.
572                  A @type field was used to specify the type for  a
573                  variable, but no other information is known about
574                  the variable.  This is typically caused by a typo
575                  in the variable name.
576
577           Unknown field tag tag.
578                  A docstring contains a field with the unknown tag
579                  tag.
580
581           Redefinition of field.
582                  Multiple field tags define the value of field  in
583                  the  same  docstring,  but  field can only take a
584                  single value.
585

EXAMPLES

587       epydoc -n epydoc -u http://epydoc.sf.net epydoc/
588              Generate the HTML API documentation  for  the  epydoc
589              package and all of its submodules, and write the out‐
590              put to the html directory.  In the headers and  foot‐
591              ers,  use epydoc as the project name, and http://epy
592              doc.sf.net as the project URL.
593
594       epydoc --pdf -n epydoc epydoc/
595              Generate the LaTeX API documentation for  the  epydoc
596              package and all of its submodules, and write the out‐
597              put to the latex directory.
598

EXIT STATUS

600       0      Successful program execution.
601
602       1      Usage error.
603
604       2      Epydoc generated an error or warning, and one of  the
605              options    --fail-on-error,   --fail-on-warning,   or
606              --fail-on-docstring-warning was specified.
607
608       other  Internal error (Python exception).
609

AUTHOR

611       Epydoc was written by Edward Loper.  This man page was orig‐
612       inally  written  by Moshe Zadka, and is currently maintained
613       by Edward Loper.
614

BUGS

616       Report bugs to <edloper@users.sourceforge.net>.
617

SEE ALSO

619       epydocgui(1)
620
621       The epydoc webpage
622              <http://epydoc.sourceforge.net>
623
624       The epytext markup language manual
625              <http://epydoc.sourceforge.net/epytext.html>
626
627
628
629                                                                     EPYDOC(1)
Impressum