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.
`string`	`_base_tree(self, uid, width, postfix)` Return the HTML code for a class's base tree.
`string`	`_breadcrumbs(self, uid)` Return the HTML code for a series of links to the ancestors of `uid`.
	`_descrlist(self, items, singular, plural, short)` Return the HTML code for a list of description items.
`markup.ParsedDocstring`	`_docstring_to_html(self, docstring, uid, indent)` Return a string containing the HTML encoding for the given `ParsedDocstring`
`boolean`	`_documented(self, uid)` Return true if the given UID is documented by the documentation map for this `HTMLFormatter`.
`list` of `UID`	`_extract_identifier_index(self)` Return a list of the `UID`s of all objects and variables documented by `_docmap`.
`list` of `(string, markup.ParsedDocstring, list of Link)`	`_extract_term_index(self)` Extract the set of terms that should be indexed from all documented docstrings.
`string`	`_find_top_page(self, pagename)` Find the top page for the API documentation.
`UID` or `None`	`_find_toplevel(self)` Return the UID of the top-level module or package, or
`int`	`_find_tree_width(self, uid)` Helper function for `_base_tree`.
`string`	`_footer(self)` Return the HTML code for the footer of a page.
`string`	`_frames_link(self, where)` Return hTML code for the frames/noframes selector.
	`_func_details_entry(self, function, container)` Return the HTML code for an entry in the function details section.
	`_func_signature(self, fname, fuid, fdoc, href, show_defaults, css_class)` Return the HTML code for the function signature of the function with the given name and documentation.
	`_get_index_terms(self, parsed_docstring, link, terms, links)` A helper function for `_extract_term_index`.
	`_group_header(self, group)`
`string`	`_header(self, name)` Return the HTML code for the header of a page with the given name.
	`_linewrap_html(self, str, linelen, maxlines)` Add line-wrapping to the HTML string `str`.
`string`	`_link_to_html(self, link)` Return the HTML code for the given link.
`None`	`_mkdir(self, directory)` If the given directory does not exist, then attempt to create it.
	`_param_to_html(self, param, show_defaults, css_class)` Return the HTML code for a single parameter.
	`_parameter_list(self, parameters, container, heading)`
	`_pprint_var_value(self, var, multiline, summary_linelen)` Return a string representation of the value of the variable `var`, suitable for use in a `<pre>...</pre>` HTML block.
	`_property_in_public_details(self, puid)` Return true if the given property should be shown in the public version of the property details section.
`string`	`_public_private_link(self, where, toc, from_private)` Return hTML code for the show/hide private selector.
`pair` of `list` of `uid.Link`	`_split_classes(self, classes_and_excepts)` Divide the classes fromt the given module into exceptions and non-exceptions.
`list` of `markup.ParsedDocstring`	`_standard_field_values(self, doc)` Return a list of epytext field values that includes all fields that are common to all `ObjDoc`s.
`string`	`_standard_fields(self, doc)` Return hTML code containing descriptions of the epytext fields that are common to all `ObjDoc`s (except for `descr`).
`string`	`_start_of(self, heading)` Return the HTML code for a 'start-of' comment.
`string`	`_summary(self, doc, uid, indent)` Return the HTML code for the summary description of the object documented by `doc`.
`string`	`_table_header(self, heading, css_class)` Return the HTML code for the start of a table.
	`_term_index_to_anchor(self, term)` Given the name of an inline index item, construct a URI anchor.
	`_uid_to_filename(self, uid)`
`string`	`_uid_to_href(self, uid, label, css_class, code)` Return the HTML code to link to the given UID.
`string`	`_uid_to_uri(self, uid)` Return a URI that points to the description of the object identified by `uid`.
	`_var_details_entry(self, var, container)` Return the HTML code for an entry in the variable details section.
	`_var_value_tooltip(self, var)` Return a string representation of the value of the variable `var`, suitable for use in a tooltip.
`None`	`_write(self, write_func, directory, filename, progress_callback, is_public, *args)` A helper for `write`, that creates new public and private streams for a given filename, and delegates writing to `write_func`.
	`_write_breadcrumbs(self, public, private, where)` Write the HTML code for the breadcrumbs line to the given streams.
	`_write_class(self, public, private, uid, doc, body_only)` Write an HTML page describing the given module to the given streams.
	`_write_class_summary(self, public, private, container, classes, heading)` Write HTML code for a class summary table.
	`_write_class_summary_row(self, public, private, link)` Write HTML code for a row in the class summary table.
	`_write_class_tree(self, public, private)` Write HTML code for a nested list showing the base/subclass relationships between all documented classes.
	`_write_class_tree_item(self, public, private, uid, depth, public_base)` Write HTML code for a list item describing a class and all of its subclasses.
`None`	`_write_css(self, directory, cssname)` Write the CSS stylesheet in the given directory.
	`_write_frames(self, public, private)` Write the frames index file for the frames-based table of contents to the given streams.
	`_write_func_details(self, public, private, container, functions, heading)` Write HTML code for a function details section.
	`_write_func_summary(self, public, private, container, functions, heading)` Write HTML code for a function summary table.
	`_write_func_summary_row(self, public, private, function, container)` Write HTML code for a row in the function summary table.
	`_write_help(self, public, private)` Write an HTML help file to the given streams.
	`_write_imports(self, public, private, doc)`
	`_write_index(self, directory, frombase)` Write an `index.html` file in the given directory.
	`_write_indices(self, public, private)` Write an HTML page containing the term and identifier indices to the given streams.
	`_write_inheritance_list(self, public, private, links, cls)` Return a string containing HTML that lists all objects from that were inherited from a base ancestor of `cls`.
	`_write_module(self, public, private, uid, doc, body_only)` Write an HTML page describing the given module to the given streams.
	`_write_module_list(self, public, private, container, modules)` Write HTML code for a list of the submodules to the given streams.
	`_write_module_toc(self, public, private, uid, doc)` Write an HTML page containing the table of contents page for the given module to the given streams.
	`_write_module_tree(self, public, private)` Write HTML code for a nested list showing the submodule relationships between all documented packages and modules.
	`_write_module_tree_item(self, public, private, uid, depth)` Write HTML for a list item describing a package/module and all of its submodules.
	`_write_navbar(self, public, private, where)` Write the HTML code for the navigation bar to the given streams.
	`_write_project_toc(self, public, private)` Write an HTML page containing the table of contents page for the whole project to the given streams.
	`_write_property_details(self, public, private, container, properties, heading)` Write HTML code for a properties details section.
	`_write_property_details_entry(self, public, private, property, container)` Write HTML code for an individual property in the properties details section.
	`_write_property_summary(self, public, private, container, properties, heading)` Write HTML code for a property summary table.
	`_write_property_summary_row(self, public, private, property, container)` Write HTML code for a row in the property summary table.
	`_write_toc(self, public, private)` Write an HTML page containing the top-level table of contents.
	`_write_toc_section(self, public, private, section, links)`
	`_write_trees(self, public, private)` Write an HTML page containing the module and class hierarchies to the given streams.
	`_write_var_details(self, public, private, container, vars, heading)` Write HTML code for a variable details section.
	`_write_var_summary(self, public, private, container, variables, heading)` Write HTML code for a variable summary table.
	`_write_var_summary_row(self, public, private, var, container)` Write HTML code for a row in the variable summary table.

Instance Variable Summary
	`_create_private_docs`: Whether or not to create documentation pages that include information about private objects.
	`_css`: The name of a file containing a CSS stylesheet; or the name of a CSS stylesheet.
`DocMap`	`_docmap`: The documentation map, encoding the objects that should be documented.
	`_frames_index`: Whether or not to create a frames-based table of contents for the documentation.
`string`	`_prj_name`: A name for the documentation (for the navbar).
`string`	`_prj_url`: A URL for the documentation (for the navpar).
	`_top_page`: The URI of the top page.
	`_variable_linelen`: The maximum line length used for displaying the values of variables in the variable details sections.
	`_variable_maxlines`: The maximum number of lines that should be displayed for the value of a variable in the variable details section.
	`_variable_tooltip_linelen`: The maximum line length for variable value tooltips.

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.

_base_tree(self, uid, width=None, postfix='')

Returns:: The HTML code for a class's base tree. The tree is drawn 'upside-down' and right justified, to allow for multiple inheritance.
(type=string)

_breadcrumbs(self, uid)

Parameters:: uid - The UID of the object whose ancestors should be listed.

Returns:: The HTML code for a series of links to the ancestors of uid.
(type=string)

_descrlist(self, items, singular, plural=None, short=0)

Parameters:: items - The description items.
(type=list of string); singular - The name of the list, if there is one element.; plural - The name of the list, if there are multiple elements.

Returns:: The HTML code for a list of description items.

_docstring_to_html(self, docstring, uid, indent=0)

Parameters:: uid
(type=None or UID)

Returns:: A string containing the HTML encoding for the given ParsedDocstring
(type=markup.ParsedDocstring)

_documented(self, uid)

Returns:: True if the given UID is documented by the documentation map for this HTMLFormatter.
(type=boolean)

_extract_identifier_index(self)

Returns:: A list of the UIDs of all objects and variables documented by _docmap. This list is used by _write_indices to construct the identifier index.
(type=list of UID)

_extract_term_index(self)

Extract the set of terms that should be indexed from all documented docstrings. Return the extracted set as a list of tuples of the form (key, term, [links]). This list is used by _write_indices to construct the term index.

Returns:: list of (string, markup.ParsedDocstring, list of Link)

_find_top_page(self, pagename)

Find the top page for the API documentation. This page is used as the default page shown in the main frame, when frames are used. When frames are not used, a redirect page is created from index.html to the top page.

Parameters:: pagename - The name of the page, as specified by the keyword argument top to the constructor.
(type=string)

Returns:: The URL of the top page.
(type=string)

_find_toplevel(self)

Returns:: The UID of the top-level module or package, or
None if there is no top-level module or package.
(type=UID or None)

_find_tree_width(self, uid)

Helper function for _base_tree.

Returns:: The width of a base tree, when drawn right-justified. This is used by _base_tree to determine how far to indent lines of the base tree.
(type=int)

_footer(self)

Returns:: The HTML code for the footer of a page.
(type=string)

_frames_link(self, where)

Parameters:: where - An identifier indiciating the page we're creating a navigation bar for. This is either a UID or the name of a file without the ".html" extension.

Returns:: HTML code for the frames/noframes selector. This selector is used to turn the frames-based table of contents on or off.
(type=string)

_func_details_entry(self, function, container)

Parameters:: function - The function that should be described by this entry.
(type=Link)

Returns:: The HTML code for an entry in the function details section. Each entry gives a complete description of a documented function.

_func_signature(self, fname, fuid, fdoc, href=0, show_defaults=1, css_class='sig')

Parameters:: fname - The short name of the function.
(type=string); fuid - The UID of the function (used to generate the optional href link).
(type=UID); fdoc - The documentation for the function.
(type=objdoc.FuncDoc); href - Whether to create an href link from the function's name to its details description.; show_defaults - Whether or not to show default values for parameters.; css_class - The CSS class that should be used to mark the signature.

Returns:: The HTML code for the function signature of the function with the given name and documentation.

_get_index_terms(self, parsed_docstring, link, terms, links)

A helper function for _extract_term_index.

For each index term t with key k in parsed_docstring, modify terms and links as follows:

Set terms[k] = t (if terms[k] doesn't exist).
Append link to links[k].

_header(self, name)

Returns:: The HTML code for the header of a page with the given name.
(type=string)

_linewrap_html(self, str, linelen, maxlines)

Add line-wrapping to the HTML string str. Line length is determined by linelen; and the maximum number of lines to display is determined by maxlines. This function treats HTML entities (e.g., &) as single characters; and ignores HTML tags (e.g., <p>).

_link_to_html(self, link)

Parameters:: link
(type=uid.Link)

Returns:: The HTML code for the given link. This code consists of an anchor with an href to the page for the link's target, and with text taken from the link's name. If the target is not documented, then the HTML code will just contain the name, and no href.
(type=string)

_mkdir(self, directory)

If the given directory does not exist, then attempt to create it.

Returns:: None

_param_to_html(self, param, show_defaults, css_class)

Parameters:: show_defaults - Whether or not to show default values for parameters.; css_class - The CSS class that should be used to mark the signature.

Returns:: The HTML code for a single parameter. Note that a single parameter can consists of a sublist of parameters (although this feature isn't often used). This is a helper function for _func_signature.

_pprint_var_value(self, var, multiline=1, summary_linelen=0)

Parameters:: var
(type=Var)

Returns:: A string representation of the value of the variable var, suitable for use in a <pre>...</pre> HTML block.

_property_in_public_details(self, puid)

Returns:: True if the given property should be shown in the public version of the property details section.

_public_private_link(self, where, toc=0, from_private=0)

Parameters:: where - An identifier indiciating the page we're creating a navigation bar for. This is either a UID or the name of a file without the ".html" extension.

Returns:: HTML code for the show/hide private selector. This selector is used to select whether private objects should be displayed.
(type=string)

_split_classes(self, classes_and_excepts)

Divide the classes fromt the given module into exceptions and non-exceptions. This is used by _write_module to list exceptions and non-exceptions separately.

Parameters:: classes_and_excepts - The list of classes to split up.
(type=list of uid.Link)

Returns:: A list (classes, excepts), where classes is the list of non-exception classes, and excepts is the list of exception classes.
(type=pair of list of uid.Link)

_standard_field_values(self, doc)

Returns:: A list of epytext field values that includes all fields that are common to all ObjDocs. _standard_field_values is used by _extract_term_index.
(type=list of markup.ParsedDocstring)

_standard_fields(self, doc)

Parameters:: doc - The object whose fields should be described.

Returns:: HTML code containing descriptions of the epytext fields that are common to all ObjDocs (except for descr).
(type=string)

_start_of(self, heading)

Parameters:: heading - The name of the section that is starting.
(type=string)

Returns:: The HTML code for a 'start-of' comment. These comments are used to deliniate sections of the HTML output.
(type=string)

_summary(self, doc, uid, indent=0)

Parameters:: doc - The documentation for the object whose summary should be returned.
(type=objdoc.ObjDoc); uid
(type=uid.UID)

Returns:: The HTML code for the summary description of the object documented by doc. A summary description is the first sentence of the doc's 'description' field. If the doc has no 'description' field, but does have a 'return' field, then the summary is taken from the return field instead.
(type=string)

_table_header(self, heading, css_class)

Parameters:: heading - The name for the table.
(type=string); css_class - The css class for the table. This is used to allow different tables to be given different styles. Currently, the following classes are used: 'summary'; 'details'; and 'index'.

Returns:: The HTML code for the start of a table. This is used by class tables, function tables, variable tables, etc.
(type=string)

_term_index_to_anchor(self, term)

Given the name of an inline index item, construct a URI anchor. These anchors are used to create links from the index page to each index item.

_uid_to_href(self, uid, label=None, css_class=None, code=1)

Parameters:: uid
(type=uid.UID); label
(type=string); code - Whether or not to include <code>...</code> tags around the label.

Returns:: The HTML code to link to the given UID. This code consists of an anchor with an href to the page for uid. If label is not None, then it is used as the text for the link; otherwise, uid is used as the text. If uid is not documented, then the HTML code will just contain the name, and no href.
(type=string)

_uid_to_uri(self, uid)

Parameters:: uid - A unique identifier for the object.
(type=UID)

Returns:: a URI that points to the description of the object identified by uid.
(type=string)

_var_details_entry(self, var, container)

Parameters:: var - The variable that should be described.

Returns:: The HTML code for an entry in the variable details section. Each entry gives a complete description of a documented variable.

_var_value_tooltip(self, var)

Parameters:: var
(type=Var)

Returns:: A string representation of the value of the variable var, suitable for use in a tooltip. In particular, use repr to convert the var to a string; truncate it to _variable_tooltip_linelen; and convert it to HTML.

_write(self, write_func, directory, filename, progress_callback, is_public, *args)

A helper for write, that creates new public and private streams for a given filename, and delegates writing to write_func. If _create_private_docs is true, then the streams are created in the 'public' and 'private' subdirectories of directory. If it's false, then the public stream is created in directory, and a _DevNull is used for the private stream.

Parameters:: write_func - The output function to delegate to. It is called with a public stream, a private stream, and any arguments given in args.; directory - The base directory for the output files; filename - The filename of the file(s) that write_func should write to.; progress_callback - A progress callback function. If it is not None, then it is called with filename before write_func is called.; is_public - Whether this is a public page. If it is not a public page, then a _DevNull will be used for the public stream. (Or if it is not a public page and _create_private_docs is false, then immediately return.); args - Extra arguments for write_func

Returns:: None

_write_breadcrumbs(self, public, private, where=None)

Write the HTML code for the breadcrumbs line to the given streams. The breadcrumbs line is an invisible table with a list of pointers to the current object's ancestors on the left; and the show/hide private selector and the frames/noframes selector on the right.

Parameters:: public - The output stream for the public version of the page.; private - The output stream for the private version of the page.; where - An identifier indicating what page we're creating a navigation bar for. This is either a UID (for an object documentation page); or a string. If it is a UID, then a list of pointers to its ancestors is displayed.

_write_class(self, public, private, uid, doc, body_only=0)

Write an HTML page describing the given module to the given streams.

Parameters:: public - The output stream for the public version of the page.; private - The output stream for the private version of the page.; uid - The UID of the module to document.; doc - The ModuleDoc of the module to document.

_write_class_summary(self, public, private, container, classes, heading='Class Summary')

Write HTML code for a class summary table. This is used by _write_module to list the classes in a module.

Parameters:: public - The output stream for the public version of the page.; private - The output stream for the private version of the page.; container - The module that contains the classes. container is used to group the classes.; classes - The classes that should be included in the list.

_write_class_summary_row(self, public, private, link)

Write HTML code for a row in the class summary table. Each row gives the name and summary of a single class.

Parameters:: public - The output stream for the public version of the page.; private - The output stream for the private version of the page.; link - A link to the class that should be described by this row.

_write_class_tree(self, public, private)

Write HTML code for a nested list showing the base/subclass relationships between all documented classes. Each element of the top-level list is a class with no (documented) bases; and under each class is listed all of its subclasses. Note that in the case of multiple inheritance, a class may appear multiple times. This is used by _write_trees to write the class hierarchy.

Parameters:: public - The output stream for the public version of the page.; private - The output stream for the private version of the page.

Bug: This function does not list public subclasses of private bases.

To Do: For multiple inheritance, don't repeat subclasses the second time a class is mentioned; instead, link to the first mention.

_write_class_tree_item(self, public, private, uid, depth=2, public_base=1)

Write HTML code for a list item describing a class and all of its subclasses. This is used by _write_class_tree to write the class hierarchy.

Parameters:: public - The output stream for the public version of the page.; private - The output stream for the private version of the page.; uid - The UID of the class tree to describe; depth - The indentation depth.; public_base - True if output should be generated for the public stream. This is prevents public classes with private bases from being listed.

Bug: This doesn't generate </li> close tags.

_write_css(self, directory, cssname)

Write the CSS stylesheet in the given directory. If cssname contains a stylesheet file or name (from epydoc.css), then use that stylesheet; otherwise, if a stylesheet file already exists, use that stylesheet. Otherwise, use the default stylesheet.

Returns:: None

_write_frames(self, public, private)

Write the frames index file for the frames-based table of contents to the given streams.

Parameters:: public - The output stream for the public version of the page.; private - The output stream for the private version of the page.

_write_func_details(self, public, private, container, functions, heading='Function Details')

Write HTML code for a function details section. This is used by _write_module to describe the functions in a module; and by _write_class to describe the methods in a class.

Parameters:: public - The output stream for the public version of the page.; private - The output stream for the private version of the page.; container - The module or class that contains the functions. container is used to group the functions.; functions - The functions that should be included in the section.

_write_func_summary(self, public, private, container, functions, heading='Function Summary')

Write HTML code for a function summary table. This is used by _write_module to list the functions in a module; and by _write_class to list the methods in a class.

Parameters:: public - The output stream for the public version of the page.; private - The output stream for the private version of the page.; container - The module or class that contains the functions. container is used to group the functions.; functions - The functions that should be included in the list.

_write_func_summary_row(self, public, private, function, container)

Write HTML code for a row in the function summary table. Each row gives a breif description of a single function.

Parameters:: public - The output stream for the public version of the page.; private - The output stream for the private version of the page.; function - The function that should be described by this row.
(type=Link)

_write_help(self, public, private)

Write an HTML help file to the given streams. If self._helpfile contains a help file, then use it; otherwise, use the default helpfile from epydoc.help.

Parameters:: public - The output stream for the public version of the page.; private - The output stream for the private version of the page.

_write_index(self, directory, frombase)

Write an index.html file in the given directory. The contents of this file are copied or linked from an existing page. The page used is determined by _frames_index and _top_page:

If _frames_index is true, then frames.html is copied.
Otherwise, the page specified by _top_page is copied.

Parameters:: frombase - True if this is the index file for the base directory when we are generating both public and private documentation. In this case, all local hyperlinks should be changed to point into the public subdirectory.
(type=boolean)

_write_indices(self, public, private)

Write an HTML page containing the term and identifier indices to the given streams.

Parameters:: public - The output stream for the public version of the page.; private - The output stream for the private version of the page.

Bug: If there are private indexed terms, but no public indexed terms, then this function will still write a header for the Term Index to the public stream.

_write_inheritance_list(self, public, private, links, cls)

Parameters:: links - The set of member objects of cls that should be listed by ancestor.
(type=list of Link); cls - The UID of the class whose inherited objects should be listed.
(type=UID)

Returns:: A string containing HTML that lists all objects from that were inherited from a base ancestor of cls. Only the objects linked to from one of the links in links are considered. The HTML lists the objects in one row of a table, grouped by ancestor.

_write_module(self, public, private, uid, doc, body_only=0)

Write an HTML page describing the given module to the given streams.

Parameters:: public - The output stream for the public version of the page.; private - The output stream for the private version of the page.; uid - The UID of the module to document.; doc - The ModuleDoc of the module to document.

_write_module_list(self, public, private, container, modules)

Write HTML code for a list of the submodules to the given streams. This is used by _write_module to list the submodules in a package.

Parameters:: public - The output stream for the public version of the page.; private - The output stream for the private version of the page.; container - The package that contains the modules (as submodules). container is used to group the modules.; modules - The modules that should be included in the list.

_write_module_toc(self, public, private, uid, doc)

Write an HTML page containing the table of contents page for the given module to the given streams. This page lists the modules, classes, exceptions, functions, and variables defined by the module.

Parameters:: public - The output stream for the public version of the page.; private - The output stream for the private version of the page.

_write_module_tree(self, public, private)

Write HTML code for a nested list showing the submodule relationships between all documented packages and modules. This is used by _write_trees to write the module hierarchy.

Parameters:: public - The output stream for the public version of the page.; private - The output stream for the private version of the page.

_write_module_tree_item(self, public, private, uid, depth=0)

Write HTML for a list item describing a package/module and all of its submodules. This is used by both _write_module_tree and _write_module_list to write package hierarchies.

Parameters:: public - The output stream for the public version of the page.; private - The output stream for the private version of the page.; uid - The UID of the module to describe; depth - The indentation depth.

Bug: This doesn't generate </li> close tags.

_write_navbar(self, public, private, where=None)

Write the HTML code for the navigation bar to the given streams. The navigation bar typically looks like:

       [ Home Trees Index Help            Project ]

Parameters:: public - The output stream for the public version of the page.; private - The output stream for the private version of the page.; where - An identifier indicating what page we're creating a navigation bar for. This is either a UID (for an object documentation page); or one of the strings 'tree', 'index', and 'help'.
(type=UID or string)

_write_project_toc(self, public, private)

Write an HTML page containing the table of contents page for the whole project to the given streams. This page lists the classes, exceptions, functions, and variables defined by any module or package in the project.

Parameters:: public - The output stream for the public version of the page.; private - The output stream for the private version of the page.

_write_property_details(self, public, private, container, properties, heading='Property Details')

Write HTML code for a properties details section. This is used by _write_class to describe the properties in a class.

Parameters:: public - The output stream for the public version of the page.; private - The output stream for the private version of the page.; container - The or class that contains the properties. container is used to group the functions.; properties - The properties that should be included in the section.

_write_property_details_entry(self, public, private, property, container)

Write HTML code for an individual property in the properties details section. This is used by _write_property_details.

Parameters:: public - The output stream for the public version of the page.; private - The output stream for the private version of the page.; property - The property that should be described by this entry.
(type=Link)

_write_property_summary(self, public, private, container, properties, heading='Property Summary')

Write HTML code for a property summary table. This is used by _write_class to list the properties in a class.

Parameters:: public - The output stream for the public version of the page.; private - The output stream for the private version of the page.; container - The module or class that contains the properties. container is used to group the properties.; properties - The properties that should be included in the list.

_write_property_summary_row(self, public, private, property, container)

Write HTML code for a row in the property summary table. Each row gives a brief description of a single property.

Parameters:: public - The output stream for the public version of the page.; private - The output stream for the private version of the page.; property - The property that should be described by this row.
(type=Link)

_write_toc(self, public, private)

Write an HTML page containing the top-level table of contents. This page is used to select a module table of contents page, or the "everything" table of contents page.

Parameters:: public - The output stream for the public version of the page.; private - The output stream for the private version of the page.

_write_trees(self, public, private)

Write an HTML page containing the module and class hierarchies to the given streams.

Parameters:: public - The output stream for the public version of the page.; private - The output stream for the private version of the page.

_write_var_details(self, public, private, container, vars, heading='Variable Details')

Write HTML code for a variable details section. This is used by _write_module to describe the variables in a module; and by _write_class to describe the instance and class variables in a class.

Parameters:: public - The output stream for the public version of the page.; private - The output stream for the private version of the page.; container - The module or class that contains the variables. container is used to group the properties.; vars - The variables that should be included in the section.

_write_var_summary(self, public, private, container, variables, heading='Variable Summary')

Write HTML code for a variable summary table. This is used by _write_module to list the variables in a module; and by _write_class to list the instance and class variables in a class.

Parameters:: public - The output stream for the public version of the page.; private - The output stream for the private version of the page.; container - The module or class that contains the variables. container is used to group the properties.; variables - The variables that should be included in the list.

_write_var_summary_row(self, public, private, var, container)

Write HTML code for a row in the variable summary table. Each row gives a brief description of a single variable.

Parameters:: public - The output stream for the public version of the page.; private - The output stream for the private version of the page.; var - The variable that should be described by this row.

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.

Instance Variable Details

_create_private_docs

Whether or not to create documentation pages that include information about private objects.

_css

The name of a file containing a CSS stylesheet; or the name of a CSS stylesheet.

_docmap

The documentation map, encoding the objects that should be documented.

Type:: DocMap

_frames_index

Whether or not to create a frames-based table of contents for the documentation.

_prj_name

A name for the documentation (for the navbar).

Type:: string

_prj_url

A URL for the documentation (for the navpar).

Type:: string

_top_page

The URI of the top page. This is the page shown in the main frame by the frames index; and the page that is used as the noframes index.

_variable_linelen

The maximum line length used for displaying the values of variables in the variable details sections.

_variable_maxlines

The maximum number of lines that should be displayed for the value of a variable in the variable details section.

_variable_tooltip_linelen

The maximum line length for variable value tooltips.

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

http://epydoc.sf.net