epydoc.html.HTMLFormatter

Package epydoc :: Module html :: Class HTMLFormatter |
[show private | hide private]
[frames | no frames]

## 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 `UID`s 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., `&amp;`) 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 `ObjDoc`s. `_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 `ObjDoc`s (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