CentOS 7.0 - man page for epydoc (centos section 1)

Linux & Unix Commands - Search Man Pages

Man Page or Keyword Search:   man
Select Man Page Set:       apropos Keyword Search (sections above)


EPYDOC(1)										EPYDOC(1)

NAME
       epydoc - generate API documentation from Python docstrings

SYNOPSIS
       epydoc [action] [options] names...

DESCRIPTION
       epydoc  generates  API  documentation for Python modules and packages, based on their doc-
       strings.  A lightweight markup language called epytext can be used to  format  docstrings,
       and  to	add information about specific fields, such as parameters and instance variables.
       Epydoc also understands docstrings written in ReStructuredText,	Javadoc,  and  plaintext.
       Currently, epydoc supports two basic output formats: HTML and LaTeX.

       The  HTML API documentation produced by epydoc consists of a set of HTML files, including:
       an API documentation page for each class and module; a syntax-highlighted source code page
       for  each  module; an identifier index page; a help page; and a frames-based table of con-
       tents.  When appropriate, epydoc will also generate index pages for bugs,  defined  terms,
       and to-do items; a class hierarchy page; and a package hierarchy page.

       The  LaTeX API documentation produced by epydoc consists of a main LaTeX file, and a LaTeX
       file for each module.  If you use --dvi, --ps, or --pdf , then epydoc will invoke external
       commands  to  convert the LaTeX output to the requested format.	Note that the LaTeX files
       containing the documentation for individual modules can be included as  chapters  or  sec-
       tions  of other LaTeX documents, using the LaTeX \include command.  If you wish to include
       individual classes in other LaTeX documents, then use  the  --separate-classes  option  to
       produce a separate LaTeX file for each class.

       epydoc  can  also be used to check the completeness of the API documentation.  By default,
       it checks that every public package, module, class, method, and function has  a	docstring
       description.  The --tests option can be used to specify additional tests to perform.

OPTIONS
       Epydoc's  options  are  divided	into  six  categories: basic options, actions, generation
       options, output options, graph options, and return value options.

       BASIC OPTIONS

	   names...
		  The list of objects that should be documented.  Objects can be specified  using
		  Python  dotted  names (such as os.path), filenames (such as epydoc/epytext.py),
		  or directory names (such as epydoc/).  Directory names  specify  packages,  and
		  are  expanded  to  include  all  sub-modules	and sub-packages.  If you wish to
		  exclude  certain  sub-modules  or  sub-packages,  use  the   --exclude   option
		  (described below).

	   --config file
		  A  configuration  file,  specifying additional optionsand/ornames.  This option
		  may be repeated.

	   --q, --quiet, --v, --verbose
		  Produce quite (or verbose) output.  If used multiple times,  this  option  pro-
		  duces successively more quiet (or verbose) output.

	   --debug
		  Show full tracebacks for internal errors.

	   --simple-term
		  Do  not  try	to  use color or cursor control when displaying the progress bar,
		  warnings, or errors.

       ACTIONS

	   --html    Write HTML output.  [default]

	   --latex   Write LaTeX output.

	   --dvi     Write DVI output.

	   --ps      Write Postscript output.

	   --pdf     Write Adobe Acrobat (pdf) output.

	   --check   Perform completeness checks on the documentation.

	   --pickle  Write the documentation to a pickle file.

       GENERATION OPTIONS

	   --docformat format
		  Set the default value for __docformat__ to format.  __docformat__ is	a  module
		  variable  that  specifies  the  markup language for the docstrings in a module.
		  Its value consists of the name of a markup language, optionally followed  by	a
		  language  code  (such  as  en for English).  For a list of the markup languages
		  currently recognized by epydoc, run epydoc --help docformat.

	   --parse-only
		  Gather all information about the documented objects  by  parsing  the  relevant
		  Python  source code; in particular, do not use introspection to gather informa-
		  tion about the documented objects.  This option should be used when  epydoc  is
		  run on untrusted code; or on code that can not be introspected because of miss-
		  ing dependencies, or because importing it would cause undesired side-effects.

	   --introspect-only
		  Gather all information about the documented objects by introspection;  in  par-
		  ticular, do not gather information by parsing the object's Python source code.

	   --exclude PATTERN
		  Do not document any object whose name matches the given regular expression pat-
		  tern.

	   --exclude-introspect PATTERN
		  Do not use introspection to gather information  about  any  object  whose  name
		  matches the given regular expression.

	   --exclude-parse PATTERN
		  Do  not  use	Python source code parsing to gather information about any object
		  whose name matches the given regular expression.

	   --inheritance format
		  The format that should be used to display  inherited	methods,  variables,  and
		  properties  in  the  generated  "summary" tables.  If format is "grouped," then
		  inherited objects are gathered into groups, based on which class that they  are
		  inherited  from.  If format is "listed," then inherited objects are listed in a
		  short list at the end of the summary table.	If  format  is	"included,"  then
		  inherited  objects are mixed in with non-inherited objects.  The default format
		  for HTML output is "grouped."

	   --show-private, --no-private
		  These options control whether documentation is generated for	private  objects.
		  By default, the generated documentation includes private objects, and users can
		  choose whether to view private objects or not, by clicking  on  "show  private"
		  and  "hide  private"	links.	But if you want to discourage users from directly
		  accessing private objects, then you may prefer not  to  generate  documentation
		  for private objects.

	   --show-imports, --no-imports
		  These options control whether module imports are included in the generated doc-
		  umentation.  By default, imports are not included.

	   --show-sourcecode, --no-sourcecode
		  These options control whether or not epydoc should generate  syntax-highlighted
		  pages containing the souce code of each module in the HTML output.  By default,
		  the sourcecode pages are generated.

	   --include-log
		  Generate an HTML page epydoc-log.html containing all error and warning messages
		  that are generated by epydoc, and include it in the generated output.

       OUTPUT OPTIONS

	   -o dir, --output dir
		  The  output  directory.  If dir does not exist, then it will be created.  If no
		  output directory is specified, then the action name (e.g., html or pdf).  html

	   -c sheet, --css sheet
		  CSS stylesheet for HTML output files.  If sheet is a file, then the  stylesheet
		  is  copied  from  that  file;  otherwise,  sheet  is	taken to be the name of a
		  built-in stylesheet.	For a list of the built-in stylesheets, run epydoc --help
		  css.	 If  a	CSS  stylesheet  is not specified, then the default stylesheet is
		  used.

	   -n name, --name name
		  The name of the project whose documentation is being generated.

	   -u url, --url url
		  The URL of the project's homepage.

	   --navlink html
		  HTML code for the homepage link on the HTML navigation bar.  If this
		  HTML	code  contains	any hyperlinks (<a href=...>), then it will be
		  inserted verbatim.  If it does not contain  any  hyperlinks,	and  a
		  project url is specified (with --url), then a hyperlink to the spec-
		  ified URL is added to the link.

	   --help-file file
		  An alternate help file.  file should contain the  body  of  an  HTML
		  file -- navigation bars will be added to it.

	   --show-frames, --no-frames
		  These options control whether HMTL output will include a frames-base
		  table of contents page.  By default, the frames-based table of  con-
		  tents is included.

	   --separate-classes
		  In  the  LaTeX  output, describe each class in a separate section of
		  the documentation, instead of including them	in  the  documentation
		  for  their  modules.	 This  creates	a separate LaTeX file for each
		  class, so it can also be useful if you want to include the  documen-
		  tation  for  one  or two classes as sections of your own LaTeX docu-
		  ment.

       GRAPH OPTIONS

	   --graph graphtype
		  Include graphs of type graphtype in the  generated  output.	Graphs
		  are generated using the Graphviz dot executable.  If this executable
		  is not on the path, then use	--dotpath  to  specify	its  location.
		  This	option	may be repeated to include multiple graph types in the
		  output.  graphtype should be one of: all, classtree,	callgraph,  or
		  umlclasstree.

	   --dotpath path
		  The path to the Graphviz dot executable.

	   --graph-font font
		  The  name of the font used to generate Graphviz graphs.  (e.g., hel-
		  vetica or times).

	   --graph-font-size size
		  The size of the font used to generate Graphviz graphs, in points.

	   --pstat file
		  A pstat output file, to be used in generating call graphs.

       RETURN VALUE OPTIONS

	   --fail-on-error
		  Return a non-zero exit status, indicating failure, if any errors are
		  encountered.

	   --fail-on-warning
		  Return  a non-zero exit status, indicating failure, if any errors or
		  warnings are encountered (not including docstring warnings).

	   --fail-on-docstring-warning
		  Return a non-zero exit status, indicating failure, if any errors  or
		  warnings are encountered (including docstring warnings).

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

       OBJECT DOCUMENTATION PAGES

	   index.html
		  The	standard   entry   point  for  the  documentation.   Normally,
		  index.html is a copy of the frames file (frames.html).  But  if  the
		  --no-frames  option  is  used,  then index.html is a copy of the API
		  documentation home page, which is normally  the  documentation  page
		  for  the  top-level package or module (or the trees page if there is
		  no top-level package or module).

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

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

	   module-pysrc.html
		  A syntax-highlighted page containing the Python source code for mod-
		  ule.	This page includes links back to the API documentation pages.

	   module-tree.html
		  The module hierarchy.

	   class-tree.html
		  The class hierarchy.	This page is only generated if	at  least  one
		  class is documented.

       INDICES

	   identifier-index.html
		  An  index  of  all  documented identifiers.  If the identifier index
		  contains more than 3,000 entries, then it will be split  into  sepa-
		  rate	pages  for each letter, named identifier-index-a.html, identi-
		  fier-index-b.html, etc.

	   term-index.html
		  An index of all explicitly marked definitional terms.  This page  is
		  only	generated  if at least one definition term is marked in a for-
		  matted docstring.

	   bug-index.html
		  An index of all explicitly marked @bug fields.  This	page  is  only
		  generated  if  at least one @bug field is listed in a formatted doc-
		  string.

	   todo-index.html
		  An index of all explicitly marked @todo fields.  This page  is  only
		  generated  if at least one @todo field is listed in a formatted doc-
		  string.

	   changed-index.html
		  An index of all explicitly marked @changed  fields.	This  page  is
		  only generated if at least one @changed field is listed in a format-
		  ted docstring.

	   deprecated-index.html
		  An index of all explicitly marked @deprecated fields.  This page  is
		  only generated if at least one @deprecated field is listed in a for-
		  matted docstring.

	   since-index.html
		  An index of all explicitly marked @since fields.  This page is  only
		  generated if at least one @since field is listed in a formatted doc-
		  string.

       FRAMES-BASED TABLE OF CONTENTS

	   frames.html
		  The main frames file.  Two frames on the left  side  of  the	window
		  contain a table of contents, and the main frame on the right side of
		  the window contains API documentation pages.

	   toc.html
		  The top-level table of contents page.  This page is displayed in the
		  upper-left   frame   of  frames.html,  and  provides	links  to  the
		  toc-everything.html and toc-module-module.html pages.

	   toc-everything.html
		  The table of contents for the entire project.   This	page  is  dis-
		  played in the lower-left frame of frames.html, and provides links to
		  every class, type, exception, function, and variable defined by  the
		  project.

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

       OTHER PAGES

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

	   redirect.html
		  This page uses javascript to translate dotted names to their	corre-
		  sponding  URLs.  For example, in epydoc's documentation, loading the
		  page <redirect.html#epydoc.apidoc.DottedName> will automatically re-
		  direct the browser to <epydoc.apidoc-module.html#DottedName>.

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

	   epydoc.js
		  A  javascript  file used to define javascript functions used by epy-
		  doc.

	   epydoc-log.html
		  A page containing a log of all warnings and errors that were	gener-
		  ated	by  epydoc, along with a table listing all of the options that
		  were used.

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

	   api.pdf
		  An Adobe Acrobat (pdf) file containing the complete  API  documenta-
		  tion.  This file is only generated if you use the --pdf option.

	   api.tex
		  The  top-level LaTeX file.  This file imports the other LaTeX files,
		  to create a single unified document.

	   api.dvi
		  A dvi file containing the complete API documentation.  This file  is
		  only	generated if you use the --dvi option, the --ps option, or the
		  --pdf option.

	   api.ps A postscript file containing the complete API  documentation.   This
		  file	is  only  generated  if  you  use the --ps option or the --pdf
		  option.

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

	   class-class.tex
		  The API documentation for a class, exception, or type.  class is the
		  complete dotted name of the class, such as  epydoc.epytext.Token  or
		  array.ArrayType.   These  class documentation files are only created
		  if the --separate-classes option is used; otherwise, the  documenta-
		  tion for each class is included in its module's documentation file.

DIAGNOSTICS
       EPYTEXT MARKUP WARNING MESSAGES
	   Epytext  errors  are  caused  by  epytext  docstrings  that contain invalid
	   markup.  Whenever an epytext error is detected, the docstring  in  question
	   is  treated	as  a  plaintext docstring.  Epydoc can generate the following
	   epytext errors:

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

	   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 initial prompt
		  line.

	   Improper heading indentation.
		  The heading for a section is not left-aligned with the paragraphs 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 construc-
		  tion (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 unbalanced 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 unbalanced 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 indi-
		  cate	an appopriate section level.  The "=" character should be used
		  to underline sections; "-" for subsections; and "~"  for  subsubsec-
		  tions.

	   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  charac-
		  ters	in  the  heading.  The number of characters in these two lines
		  must match exactly for them to be considered a heading.

       FIELD WARNINGS
	   Field warnings are caused by docstrings  containing	invalid  fields.   The
	   contents  of  the invalid field are generally ignored.  Epydoc 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 requires 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.

EXAMPLES
       epydoc -n epydoc -u http://epydoc.sf.net epydoc/
	      Generate the HTML API documentation for the epydoc package  and  all  of
	      its  submodules,	and  write  the  output to the html directory.	In the
	      headers and footers, use epydoc as the  project  name,  and  http://epy-
	      doc.sf.net as the project URL.

       epydoc --pdf -n epydoc epydoc/
	      Generate	the  LaTeX API documentation for the epydoc package and all of
	      its submodules, and write the output to the latex directory.

EXIT STATUS
       0      Successful program execution.

       1      Usage error.

       2      Epydoc  generated  an  error  or	warning,  and  one  of	 the   options
	      --fail-on-error,	--fail-on-warning,  or --fail-on-docstring-warning was
	      specified.

       other  Internal error (Python exception).

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

BUGS
       Report bugs to <edloper@users.sourceforge.net>.

SEE ALSO
       epydocgui(1)

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

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

											EPYDOC(1)
Unix & Linux Commands & Man Pages : ©2000 - 2018 Unix and Linux Forums


All times are GMT -4. The time now is 03:40 AM.

Unix & Linux Forums Content Copyright©1993-2018. All Rights Reserved.
×
UNIX.COM Login
Username:
Password:  
Show Password





Not a Forum Member?
Forgot Password?