Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
EPYDOCGUI(1)		    General Commands Manual		  EPYDOCGUI(1)

NAME
       epydocgui - graphical interface to epydoc

SYNOPSIS
       epydocgui [project.prj |	modules...]

       epydoc -h

       epydoc -V

DESCRIPTION
       epydocgui is a graphical	interface to epydoc, which generates API docu-
       mentation for Python modules and	packages, based	on  their  docstrings.
       A lightweight markup language called epytext can	be used	to format doc-
       strings,	and to add information about specific fields, such as  parame-
       ters and	instance variables.

       The  API	 documentation produced	by epydocgui consists of a set of HTML
       files.  Two subdirectories are created for the public and private docu-
       mentation.  Within each subdirectories, every class and module is docu-
       mented in its own file.	An index file, a trees file, and a  help  file
       are also	created.  If you select	the frames option, then	a frames-based
       table of	contents is also produced.

OPTIONS
       project.prj
	      The name of a  project  file  that  was  saved  with  epydocgui.
	      Project  files record a list of related modules, and the options
	      that should be used to generate the documentation	for those mod-
	      ules.

       modules...
	      The  list	of the modules that should be documented.  Modules can
	      be specified using module	names  (such  as  os.path),  filenames
	      (such  as	 epydoc/epytext.py),  or directory names (such as epy-
	      doc/).  Directory	names specify packages,	and  are  expanded  to
	      include all sub-modules and sub-packages.

       -h, --help, --usage, -?
	      Display a	usage message.

       -V, --version
	      Print the	version	of Epydoc.

HTML FILES
       The  API	 documentation	produced  by  epydoc consists of the following
       files:

	   index.html
		  The standard entry point for the  documentation.   Normally,
		  index.html  is  a  frame  index  file,  which	 defines three
		  frames: two frames on	the left side of the browser contain a
		  table	 of  contents, and the main frame on the right side of
		  the  window  contains	 documentation	pages.	 But  if   the
		  --no-frames  option  is  used, then index.html will redirect
		  the user to the project's top	page.

	   m-module.html
		  The API documentation	for a module.  module is the  complete
		  dotted name of the module, such as sys or epydoc.epytext.

	   c-class.html
		  The  API  documentation  for	a  class,  exception, or type.
		  class	is the complete	dotted name of the class, such as epy-
		  doc.epytext.Token or array.ArrayType.

	   trees.html
		  The module and class hierarchies.

	   indices.html
		  The term  and	identifier indices.

	   help.html
		  The  help  page  for the project.  This page explains	how to
		  use and navigate the webpage produced	by epydoc.

	   toc.html
		  The top-level	table of contents page.	  This	page  is  dis-
		  played  in  the  upper-left  frame,  and  provides  links to
		  toc-everything.html	and   the   toc-m-module.html	files.
		  toc.html is not generated if the --no-frames option is used.

	   toc-everything.html
		  The  table of	contents for the entire	project.  This page is
		  displayed in the lower-left frame, and provides links	to ev-
		  ery  class,  type, exception,	function, and variable defined
		  by the project.  toc-everything.html is not generated	if the
		  --no-frames option is	used.

	   toc-m-module.html
		  The  table of	contents for a module.	This page is displayed
		  in the lower-left frame, and provides	links to every	class,
		  type,	 exception, function, and variable defined by the mod-
		  ule.	module is the complete dotted name of the module, such
		  as  sys  or epydoc.epytext.  toc-m-module.html is not	gener-
		  ated if the --no-frames option is used.

	   epydoc.css
		  The CSS stylesheet used to display all HTML pages.

       By default, epydoc creates two subdirectories in	the output  directory:
       public and private.  Each directory contains all	of the files specified
       above.  But if the --no-private option is used, then no	subdirectories
       are  created,  and  the public documentation is written directly	to the
       output directory.  ivided into five categories: import errors;  epytext
       errors; epytext warnings; field warnings; and inspection	errors.	 When-
       ver epydoc encounters an	error, it issues a warning  message  that  de-
       scribes the error, and attempts to continue generating documentation.

       Import  errors indicate that epydoc was unable to import	a module.  Im-
       port errors typically prevent epydoc from generating documentation  for
       the  module  in question.  Epydoc can generate the following import er-
       rors:

	   Bad module name module
		  Epydoc attempted to import module, but module	is not a valid
		  name for a Python module.

	   Could not find a UID	for link-target
		  Epydoc  was  unable to find the object referred to by	an in-
		  line link construction (L{...}).  This is usually caused  by
		  a typo in the	link.

	   Could not import module
		  Epydoc attempted to import module, but it failed.  This typ-
		  ically occurs	when module raises an exception.

	   file	does not exist
		  Epydoc attempted to import the module	contained in file, but
		  file does not	exist.

       Epytext	errors	are  caused by epytext docstrings that contain invalid
       markup.	Whenever an epytext error is detected, the docstring in	 ques-
       tion is treated as a plaintext docstring.  Epydoc can generate the fol-
       lowing epytext errors:

	   Bad link target.
		  The target specified for an inline link contruction (L{...})
		  is not well-formed.  Link targets must be valid python iden-
		  tifiers.

	   Bad uri target.
		  The target specified for an inline uri contruction  (U{...})
		  is  not well-formed.	This typically occurs if inline	markup
		  is nested inside the URI target.

	   Fields must be at the top level.
		  The list of fields (@param,  etc.)   is  contained  by  some
		  other	block structure	(such as a list	or a section).

	   Fields must be the final elements.
		  The  list  of	 fields	(@param, etc.)	is not at the end of a
		  docstring.

	   Headings must occur at top level.
		  The heading is contianed in some other block structure (such
		  as a list).

	   Improper doctest block indentation.
		  The  doctest	block dedents past the indentation of its ini-
		  tial prompt line.

	   Improper heading indentation.
		  The heading for a section is not left-aligned	with the para-
		  graphs in the	section	that contains it.

	   Improper paragraph indentation.
		  The  paragraphs  within  a block are not left-aligned.  This
		  error	is  often  generated  when  plaintext  docstrings  are
		  parsed using epytext.

	   Invalid escape.
		  An  unknown  escape sequence was used	with the inline	escape
		  construction (E{...}).

	   Lists must be indented.
		  An unindented	line immediately following a paragraph	starts
		  with a list bullet.  Epydoc is not sure whether you meant to
		  start	a new list item, or meant for a	paragraph to include a
		  word	that looks like	a bullet.  If you intended the former,
		  then indent the list.	 If  you  intended  the	 latter,  then
		  change  the  word-wrapping  of  the paragraph, or escape the
		  first	character of the word that looks like a	bullet.

	   Unbalanced '{'.
		  The docstring	contains unbalanced braces.  Epytext  requires
		  that	all  braces must be balanced.  To include a single un-
		  balanced brace, use the escape sequences E{lb} (left	brace)
		  and E{rb} (right brace).

	   Unbalanced '}'.
		  The  docstring contains unbalanced braces.  Epytext requires
		  that all braces must be balanced.  To	include	a  single  un-
		  balanced  brace, use the escape sequences E{lb} (left	brace)
		  and E{rb} (right brace).

	   Unknown inline markup tag.
		  An unknown tag was used with the inline markup  construction
		  ( x{...} ).

	   Wrong underline character for heading.
		  The  underline  character used for this section heading does
		  not indicate an appopriate section level.  The "=" character
		  should  be  used to underline	sections; "-" for subsections;
		  and "~" for subsubsections.

       Epytext warnings	are caused by epytext docstrings  that	contain	 ques-
       tionable	 or  suspicious	 markup.   Epytext warnings do not prevent the
       docstring in question from being	parsed.	 Epydoc	can generate the  fol-
       lowing epytext warnings:

	   Possible mal-formatted field	item.
		  Epytext detected a line that looks like a field item,	but is
		  not correctly	formatted.  This  typically  occurs  when  the
		  trailing colon (":") is not included in the field tag.

	   Possible heading typo.
		  Epytext  detected a pair of lines that looks like a heading,
		  but the number of underline characters does  not  match  the
		  number  of characters	in the heading.	 The number of charac-
		  ters in these	two lines must match exactly for  them	to  be
		  considered a heading.

       Field  warnings	are  caused  by	 epytext docstrings containing invalid
       fields.	The contents of	the invalid field are generally	ignored.  Epy-
       doc can generate	the following field warnings:

	   @param for unknown parameter	param.
		  A  @param field was used to specify the type for a parameter
		  that is not included in the function's signature.   This  is
		  typically caused by a	typo in	the parameter name.

	   tag did not expect an argument.
		  The field tag	tag was	used with an argument, but it does not
		  take one.

	   tag expected	an argument.
		  The field tag	tag was	used without an	argument, but  it  re-
		  quires one.

	   @type for unknown parameter param.
		  A  @type  field was used to specify the type for a parameter
		  that is not included in the function's signature.   This  is
		  typically caused by a	typo in	the parameter name.

	   @type for unknown variable var.
		  A  @type  field was used to specify the type for a variable,
		  but no other information is known about the variable.	  This
		  is typically caused by a typo	in the variable	name.

	   Unknown field tag tag.
		  A docstring contains a field with the	unknown	tag tag.

	   Redefinition	of field.
		  Multiple  field  tags	 define	the value of field in the same
		  docstring, but field can only	take a single value.

       Inspection errors are generated if epydoc encounters problems while at-
       tempting	to inspect the properties of a documented object.  Most	of in-
       spection	errors do not prevent epydoc from documenting  the  object  in
       question.  Epydoc can generate the following inspection errors:

	   The parameters of inhmethod do not match basemethod.
		  The  parameters  of the undocumented method inhmethod	do not
		  match	the parameters of the  base  class  method  basemethod
		  that	it overrides.  As a result, inhmethod does not inherit
		  documentation	from basemethod.  If the difference in parame-
		  ters	is  intentional, then you can eliminate	the warning by
		  adding a (possibly empty) docstring to inhmethod.

	   Docmap cannot add a type
		  Epydoc attempted to document an object with an unknown type.
		  This	error  is  typically generated by packages and modules
		  that manipulate the import mechanism,	such that importing  a
		  module produces some other type of object.

	   UID conflict	detected: uid
		  Two  different objects were assigned the same	unique identi-
		  fier by epydoc.  This	can cause  epydoc  to  substitute  the
		  documentation	 of  one  object with the documentation	of an-
		  other	object that is assigned	the  same  unique  identifier.
		  However,  this  will	usually	only cause problems if the two
		  objects with the same	unique identifiers are both modules or
		  classes,  in	which  case the	API documentation page for one
		  object will overwrite	the API	 documentation	page  for  the
		  other	object.

	   object appears in multiple builtin modules
		  While	 attempting  to	 determine  which  module  defines the
		  builtin object object, epydoc	 encountered  multiple	candi-
		  dates, and was unable	to decide which	candidate was correct.
		  In this case,	epydoc arbitrarily chooses the first candidate
		  that it finds.

	   object appears in multiple .py modules
		  While	 attempting  to	 determine  which  module  defines the
		  builtin object object, epydoc	 encountered  multiple	candi-
		  dates, and was unable	to decide which	candidate was correct.
		  In this case,	epydoc arbitrarily chooses the first candidate
		  that it finds.

	   object appears in multiple .so modules
		  While	 attempting  to	 determine  which  module  defines the
		  builtin object object, epydoc	 encountered  multiple	candi-
		  dates, and was unable	to decide which	candidate was correct.
		  In this case,	epydoc arbitrarily chooses the first candidate
		  that it finds.

	   Could not find a module for object
		  Epydoc  was unable to	determine which	module defines object.
		  If object is a function, then	this will prevent epydoc  from
		  generating  any  documentation for object, since it does not
		  know what page to put	the documentation on.  Otherwise, this
		  will	prevent	 the documentation for object from including a
		  link to its containing module.

AUTHOR
       Epydoc was written by Edward Loper.  This man page was originally writ-
       ten by Moshe Zadka, and is currently maintained by Edward Loper.

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

SEE ALSO
       epydoc(1)

       The epydoc webpage
	      <http://epydoc.sourceforge.net>

       The epytext markup language manual
	      <http://epydoc.sourceforge.net/epytext.html>

								  EPYDOCGUI(1)

NAME | SYNOPSIS | DESCRIPTION | OPTIONS | HTML FILES | AUTHOR | BUGS | SEE ALSO

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=epydocgui&sektion=1&manpath=FreeBSD+12.1-RELEASE+and+Ports>

home | help