epydoc.html.HTMLFormatter

Package epydoc :: Module html :: Class HTMLFormatter

[show private | hide private]

Class HTMLFormatter

Documentation to HTML converter. The API documentation produced HTMLFormatter consists of a set of HTML files. Two subdirectories are created for the public and private documentation. Within each subdirectories, every class and module is documented in its own file. An index file, a trees file, a help file, and a frames-based table of contents are also created. In particular, HTMLFormatter generates 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.
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.
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 displayed in the upper-left frame, and provides links to toc-everything.html and the toc-module-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 every class, type, exception, function, and variable defined by the project. toc-everything.html is not generated if the --no-frames option is used.
toc-module-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 module. module is the complete dotted name of the module, such as sys or epydoc.epytext. toc-m-module.html is not generated if the --no-frames option is used.
epydoc.css: The CSS stylesheet used to display all HTML pages.

Method Summary
	`__init__(self, docmap, **kwargs)` Construct a new HTML formatter, using the given documentation map.
	`format(object, error_stream, show_private, body_only, *options)` Return a string containing the HTML documentation for the given object. (Static method)*
`int`	`num_files(self)` Return the number of files that this `HTMLFormatter` will generate.
`None`	`write(self, directory, progress_callback)` Write the documentation to the given directory.

Instance Method Details

init(self, docmap, **kwargs)
(Constructor)

Construct a new HTML formatter, using the given documentation map.

Parameters:: docmap - The documentation to output.
(type=DocMap)

Keyword Parameters:: prj_name - The name of the project. Defaults to none.
(type=string); prj_url - The target for the project hopeage link on the navigation bar. If prj_url is not specified, then no hyperlink is created.
(type=string); prj_link - The label for the project link on the navigation bar. This link can contain arbitrary HTML code (e.g. images). By default, a label is constructed from prj_name.
(type=string); top - The top page for the documentation. This is the default page shown main frame, when frames are enabled. top can be a URL, the name of a module, the name of a class, or one of the special strings "trees.html", "indices.html", or "help.html". By default, the top-level package or module is used, if there is one; otherwise, "trees" is used.
(type=string); css - The CSS stylesheet file. If css is a file name, then the specified file's conents will be used. Otherwise, if css is the name of a CSS stylesheet in epydoc.css, then that stylesheet will be used. Otherwise, an error is reported. If no stylesheet is specified, then the default stylesheet is used.
(type=string); private_css - The CSS stylesheet file for the private API documentation. If css is a file name, then the specified file's conents will be used. Otherwise, if css is the name of a CSS stylesheet in epydoc.css, then that stylesheet will be used. Otherwise, an error is reported. If no stylesheet is specified, then the private API documentation will use the same stylesheet as the public API documentation.
(type=string); help - The name of the help file. If no help file is specified, then the default help file will be used.
(type=string); private - Whether to create documentation for private objects. By default, private objects are documented.
(type=boolean); frames - Whether to create a frames-based table of contents. By default, it is produced.
(type=boolean)); show_imports - Whether or not to display lists of imported functions and classes. By default, they are not shown.
(type=boolean); index_parameters - Whether or not to include function parameters in the identifier index. By default, they are not included.
(type=boolean); variable_maxlines - The maximum number of lines that should be displayed for the value of a variable in the variable details section. By default, 8 lines are displayed.
(type=int); variable_linelength - The maximum line length used for displaying the values of variables in the variable details sections. If a line is longer than this length, then it will be wrapped to the next line. The default line length is 70 characters.
(type=int); variable_summary_linelength - The maximum line length used for displaying the values of variables in the summary section. If a line is longer than this length, then it will be truncated. The default is 40 characters.
(type=int); variable_tooltip_linelength - The maximum line length used for tooltips for the values of variables. If a line is longer than this length, then it will be truncated. The default is 600 characters.
(type=int); property_function_linelength - The maximum line length used to dispaly property functions (fget, fset, and fdel) that contain something other than a function object. The dfeault length is 40 characters.
(type=int); inheritance - How inherited objects should be displayed. If inheritance='grouped', then inherited objects are gathered into groups; if inheritance='listed', then inherited objects are listed in a short list at the end of their group; if inheritance='included', then inherited objects are mixed in with non-inherited objects. The default is 'grouped'.
(type=string)

num_files(self)

Returns:: The number of files that this HTMLFormatter will generate.
(type=int)

write(self, directory=None, progress_callback=None)

Write the documentation to the given directory.

Parameters:: directory - The directory to which output should be written. If no directory is specified, output will be written to the current directory. If the directory does not exist, it will be created.
(type=string); progress_callback - A callback function that is called before each file is written, with the name of the created file.
(type=function)

Returns:: None

Raises:: OSError - If directory cannot be created,; OSError - If any file cannot be created or written to.

Static Method Details

format(object, error_stream=None, show_private=1, body_only=1, **options)

Parameters:: object - The object to document. object can be a module, a class, a function, a method, or a property; or it can be the UID of any object; or it can be a Link to any object.; error_stream - A file or stream where errors and warnings will be written. If error_stream is unspecified, then warnings and errors are discarded.; show_private - If true, then include private objects in the output; if false, then only include public objects.; body_only - If true, then don't include navigation bars and breadcrumbs when generating the HTML documentation for a module or a class. If false, then do include them.; options - Options for the HTMLFormatter object that will be used to generate the HTML. See HTMLFormatter.__init__ for a complete list of options.

Returns:: A string containing the HTML documentation for the given object.

Generated by Epydoc 2.1 on Sat Mar 20 17:46:11 2004

http://epydoc.sf.net

Class HTMLFormatter

__init__(self, docmap, **kwargs) (Constructor)

num_files(self)

write(self, directory=None, progress_callback=None)

format(object, error_stream=None, show_private=1, body_only=1, **options)

init(self, docmap, **kwargs)
(Constructor)