t.l.tree : module documentation

No module docstring

Function	fixLinks	Rewrite links to XHTML lore input documents so they point to lore XHTML output documents.
Function	addMtime	Set the last modified time of the given document.
Function	fixAPI	Replace API references with links to API documentation.
Function	fontifyPython	Syntax color any node in the given document which contains a Python source listing.
Function	fontifyPythonNode	Syntax color the given node containing Python source code.
Function	addPyListings	Insert Python source listings into the given document from files in the given directory based on `py-listing` nodes.
Function	addHTMLListings	Insert HTML source listings into the given document from files in the given directory based on `html-listing` nodes.
Function	addPlainListings	Insert text listings into the given document from files in the given directory based on `listing` nodes.
Function	getHeaders	Return all H2 and H3 nodes in the given document.
Function	generateToC	Create a table of contents for the given document.
Function	putInToC	Insert the given table of contents into the given document.
Function	removeH1	Replace all `h1` nodes in the given document with empty `span` nodes.
Function	footnotes	Find footnotes in the given document, move them to the end of the body, and generate links to them.
Function	notes	Find notes in the given document and mark them up as such.
Function	compareMarkPos	Perform in every way identically to `cmp` for valid inputs.
Function	comparePosition	Compare the two elements given by their position in the document or documents they were parsed from.
Function	findNodeJustBefore	Find the last Element which is a sibling of `target` and is in `nodes`.
Function	getFirstAncestorWithSectionHeader	Visit the ancestors of `entry` until one with at least one `h2` child node is found, then return all of that node's `h2` child nodes.
Function	getSectionNumber	Retrieve the section number of the given node.
Function	getSectionReference	Find the section number which contains the given node.
Function	index	Extract index entries from the given document and store them for later use and insert named anchors so that the index can link back to those entries.
Function	setIndexLink	Insert a link to an index document.
Function	numberDocument	Number the sections of the given document.
Function	fixRelativeLinks	Replace relative links in `str` and `href` attributes with links relative to `linkrel`.
Function	setTitle	Add title and chapter number information to the template document.
Function	setAuthors	Add author information to the template document.
Function	setVersion	Add a version indicator to the given template.
Function	getOutputFileName	Return a filename which is the same as `originalFileName` except for the extension, which is replaced with `outputExtension`.
Function	munge	Mutate `template` until it resembles `document`.
Function	parseFileAndReport	Parse and return the contents of the given lore XHTML document.
Function	makeSureDirectoryExists	Undocumented
Function	doFile	Process the input document at `filename` and write an output document.
Function	_getAPI	Retrieve the fully qualified Python name represented by the given node.
Function	_makeLineNumbers	Return an element which will render line numbers for a source listing.
Function	_replaceWithListing	Undocumented
Class	_LocationReportingErrorHandler	Define a SAX error handler which can report the location of fatal errors.
Class	_TagTrackingContentHandler	Define a SAX content handler which keeps track of the start location of all open tags. This information is used by the above defined error handler to report useful locations when a fatal error is encountered.
Class	_LocalEntityResolver	Implement DTD loading (from a local source) for the limited number of DTDs which are allowed for Lore input documents.
Function	_writeDocument	Serialize the given node to XML into the named file.

def fixLinks(document, ext): (source)

Rewrite links to XHTML lore input documents so they point to lore XHTML output documents.

Any node with an href attribute which does not contain a value starting with http, https, ftp, or mailto and which does not have a class attribute of absolute or which contains listing and which does point to an URL ending with html will have that attribute value rewritten so that the filename extension is ext instead of html.

Parameters	document	The input document which contains all of the content to be presented. (type: A DOM Node or Document )
	ext	The extension to use when selecting an output file name. This replaces the extension of the input file name. (type: `str` )
Returns	`None`

def addMtime(document, fullpath): (source)

Set the last modified time of the given document.

Parameters	document	The output template which defines the presentation of the last modified time. (type: A DOM Node or Document )
	fullpath	The file name from which to take the last modified time. (type: `str` )
Returns	`None`

def _getAPI(node): (source)

Retrieve the fully qualified Python name represented by the given node.

The name is represented by one or two aspects of the node: the value of the node's first child forms the end of the name. If the node has a base attribute, that attribute's value is prepended to the node's value, with . separating the two parts.

Returns The fully qualified Python name. (type: str )

def fixAPI(document, url): (source)

Replace API references with links to API documentation.

Parameters	document	The input document which contains all of the content to be presented. (type: A DOM Node or Document )
	url	A string which will be interpolated with the fully qualified Python name of any API reference encountered in the input document, the result of which will be used as a link to API documentation for that name in the output document. (type: `str` )
Returns	`None`

def fontifyPython(document): (source)

Syntax color any node in the given document which contains a Python source listing.

Parameters	document	The input document which contains all of the content to be presented. (type: A DOM Node or Document )
Returns	`None`

def fontifyPythonNode(node): (source)

Syntax color the given node containing Python source code.

The node must have a parent.

Returns None

def addPyListings(document, dir): (source)

Insert Python source listings into the given document from files in the given directory based on py-listing nodes.

Any node in document with a class attribute set to py-listing will have source lines taken from the file named in that node's href attribute (searched for in dir) inserted in place of that node.

If a node has a skipLines attribute, its value will be parsed as an integer and that many lines will be skipped at the beginning of the source file.

Parameters	document	The document within which to make listing replacements. (type: A DOM Node or Document )
	dir	The directory in which to find source files containing the referenced Python listings. (type: `str` )
Returns	`None`

def _makeLineNumbers(howMany): (source)

Return an element which will render line numbers for a source listing.

Parameters	howMany	The number of lines in the source listing. (type: `int` )
Returns	An `dom.Element` which can be added to the document before the source listing to add line numbers to it.

def _replaceWithListing(node, val, filename, class_): (source)

Undocumented

def addHTMLListings(document, dir): (source)

Insert HTML source listings into the given document from files in the given directory based on html-listing nodes.

Any node in document with a class attribute set to html-listing will have source lines taken from the file named in that node's href attribute (searched for in dir) inserted in place of that node.

Parameters	document	The document within which to make listing replacements. (type: A DOM Node or Document )
	dir	The directory in which to find source files containing the referenced HTML listings. (type: `str` )
Returns	`None`

def addPlainListings(document, dir): (source)

Insert text listings into the given document from files in the given directory based on listing nodes.

Any node in document with a class attribute set to listing will have source lines taken from the file named in that node's href attribute (searched for in dir) inserted in place of that node.

Parameters	document	The document within which to make listing replacements. (type: A DOM Node or Document )
	dir	The directory in which to find source files containing the referenced text listings. (type: `str` )
Returns	`None`

def getHeaders(document): (source)

Return all H2 and H3 nodes in the given document.

Parameters	document	(type: A DOM Node or Document )
Returns	(type: `list` )

def generateToC(document): (source)

Create a table of contents for the given document.

Parameters	document	(type: A DOM Node or Document )
Returns	a Node containing a table of contents based on the headers of the given document. (type: A DOM Node )

def putInToC(document, toc): (source)

Insert the given table of contents into the given document.

The node with class attribute set to toc has its children replaced with toc.

Parameters	document	(type: A DOM Node or Document )
	toc	(type: A DOM Node )

def removeH1(document): (source)

Replace all h1 nodes in the given document with empty span nodes.

h1 nodes mark up document sections and the output template is given an opportunity to present this information in a different way.

Parameters	document	The input document which contains all of the content to be presented. (type: A DOM Node or Document )
Returns	`None`

def footnotes(document): (source)

Find footnotes in the given document, move them to the end of the body, and generate links to them.

A footnote is any node with a class attribute set to footnote. Footnote links are generated as superscript. Footnotes are collected in a ol node at the end of the document.

Parameters	document	The input document which contains all of the content to be presented. (type: A DOM Node or Document )
Returns	`None`

def notes(document): (source)

Find notes in the given document and mark them up as such.

A note is any node with a class attribute set to note.

(I think this is a very stupid feature. When I found it I actually exclaimed out loud. -exarkun)

Parameters	document	The input document which contains all of the content to be presented. (type: A DOM Node or Document )
Returns	`None`

def compareMarkPos(a, b): (source)

Perform in every way identically to cmp for valid inputs.

def comparePosition(firstElement, secondElement): (source)

Compare the two elements given by their position in the document or documents they were parsed from.

Parameters	firstElement	(type: `dom.Element` )
	secondElement	(type: `dom.Element` )
Returns	`-1`, `0`, or `1`, with the same meanings as the return value of `cmp`.

def findNodeJustBefore(target, nodes): (source)

Find the last Element which is a sibling of target and is in nodes.

Parameters	target	A node the previous sibling of which to return.
	nodes	A list of nodes which might be the right node.
Returns	The previous sibling of `target`.

def getFirstAncestorWithSectionHeader(entry): (source)

Visit the ancestors of entry until one with at least one h2 child node is found, then return all of that node's h2 child nodes.

Parameters	entry	The node from which to begin traversal. This node itself is excluded from consideration. (type: A DOM Node )
Returns	All `h2` nodes of the ultimately selected parent node. (type: `list` of DOM Nodes )

def getSectionNumber(header): (source)

Retrieve the section number of the given node.

This is probably intended to interact in a rather specific way with numberDocument.

Parameters	header	The section from which to extract a number. The section number is the value of this node's first child. (type: A DOM Node or `None` )
Returns	`None` or a `str` giving the section number.

def getSectionReference(entry): (source)

Find the section number which contains the given node.

This function looks at the given node's ancestry until it finds a node which defines a section, then returns that section's number.

Parameters	entry	The node for which to determine the section. (type: A DOM Node )
Returns	The section number, as returned by `getSectionNumber` of the first ancestor of `entry` which defines a section, as determined by `getFirstAncestorWithSectionHeader`. (type: `str` )

def index(document, filename, chapterReference): (source)

Extract index entries from the given document and store them for later use and insert named anchors so that the index can link back to those entries.

Any node with a class attribute set to index is considered an index entry.

Parameters	document	The input document which contains all of the content to be presented. (type: A DOM Node or Document )
	filename	A link to the output for the given document which will be included in the index to link to any index entry found here. (type: `str` )
	chapterReference	??? (type: ??? )
Returns	`None`

def setIndexLink(template, indexFilename): (source)

Insert a link to an index document.

Any node with a class attribute set to index-link will have its tag name changed to a and its href attribute set to indexFilename.

Parameters	template	The output template which defines the presentation of the version information. (type: A DOM Node or Document )
	indexFilename	The address of the index document to which to link. If any `False` value, this function will remove all index-link nodes. (type: `str` )
Returns	`None`

def numberDocument(document, chapterNumber): (source)

Number the sections of the given document.

A dot-separated chapter, section number is added to the beginning of each section, as defined by h2 nodes.

This is probably intended to interact in a rather specific way with getSectionNumber.

Parameters	document	The input document which contains all of the content to be presented. (type: A DOM Node or Document )
	chapterNumber	The chapter number of this content in an overall document. (type: `int` )
Returns	`None`

def fixRelativeLinks(document, linkrel): (source)

Replace relative links in str and href attributes with links relative to linkrel.

Parameters	document	The output template. (type: A DOM Node or Document )
	linkrel	An prefix to apply to all relative links in `src` or `href` attributes in the input document when generating the output document. (type: `str` )

def setTitle(template, title, chapterNumber): (source)

Add title and chapter number information to the template document.

The title is added to the end of the first title tag and the end of the first tag with a class attribute set to title. If specified, the chapter is inserted before the title.

Parameters	template	The output template which defines the presentation of the version information. (type: A DOM Node or Document )
	title	Nodes from the input document defining its title. (type: `list` of DOM Nodes )
	chapterNumber	The chapter number of this content in an overall document. If not applicable, any `False` value will result in this information being omitted. (type: `int` )
Returns	`None`

def setAuthors(template, authors): (source)

Add author information to the template document.

Names and contact information for authors are added to each node with a class attribute set to authors and to the template head as link nodes.

Parameters	template	The output template which defines the presentation of the version information. (type: A DOM Node or Document )
	authors	List of names and contact information for the authors of the input document. (type: `list` of two-tuples of `str` )
Returns	`None`

def setVersion(template, version): (source)

Add a version indicator to the given template.

Parameters	template	The output template which defines the presentation of the version information. (type: A DOM Node or Document )
	version	The version string to add to the template. (type: `str` )
Returns	`None`

def getOutputFileName(originalFileName, outputExtension, index=None): (source)

Return a filename which is the same as originalFileName except for the extension, which is replaced with outputExtension.

For example, if originalFileName is '/foo/bar.baz' and outputExtension is 'quux', the return value will be '/foo/bar.quux'.

Parameters	originalFileName	(type: `str` )
	outputExtension	(type: `stR` )
	index	ignored, never passed.
Returns	(type: `str` )

def munge(document, template, linkrel, dir, fullpath, ext, url, config, outfileGenerator=getOutputFileName): (source)

Mutate template until it resembles document.

Parameters	document	The input document which contains all of the content to be presented. (type: A DOM Node or Document )
	template	The template document which defines the desired presentation format of the content. (type: A DOM Node or Document )
	linkrel	An prefix to apply to all relative links in `src` or `href` attributes in the input document when generating the output document. (type: `str` )
	dir	The directory in which to search for source listing files. (type: `str` )
	fullpath	The file name which contained the input document. (type: `str` )
	ext	The extension to use when selecting an output file name. This replaces the extension of the input file name. (type: `str` )
	url	A string which will be interpolated with the fully qualified Python name of any API reference encountered in the input document, the result of which will be used as a link to API documentation for that name in the output document. (type: `str` )
	config	Further specification of the desired form of the output. Valid keys in this dictionary: noapi: If present and set to a True value, links to API documentation will not be generated. version: A string which will be included in the output to indicate the version of this documentation. (type: `dict` )
	outfileGenerator	Output filename factory. This is invoked with the intput filename and `ext` and the output document is serialized to the file with the name returned. (type: Callable of `str`, `str` returning `str` )
Returns	`None`

def parseFileAndReport(filename, _open=file): (source)

Parse and return the contents of the given lore XHTML document.

Parameters	filename	The name of a file containing a lore XHTML document to load. (type: `str` )
Returns	The document contained in `filename`. (type: A DOM Document )
Raises	process.ProcessingFailure	When the contents of the specified file cannot be parsed.

def makeSureDirectoryExists(filename): (source)

Undocumented

def doFile(filename, linkrel, ext, url, templ, options={}, outfileGenerator=getOutputFileName): (source)

Process the input document at filename and write an output document.

Parameters	filename	The path to the input file which will be processed. (type: `str` )
	linkrel	An prefix to apply to all relative links in `src` or `href` attributes in the input document when generating the output document. (type: `str` )
	ext	The extension to use when selecting an output file name. This replaces the extension of the input file name. (type: `str` )
	url	A string which will be interpolated with the fully qualified Python name of any API reference encountered in the input document, the result of which will be used as a link to API documentation for that name in the output document. (type: `str` )
	templ	The template on which the output document will be based. This is mutated and then serialized to the output file. (type: A DOM Node or Document )
	options	Further specification of the desired form of the output. Valid keys in this dictionary: noapi: If present and set to a True value, links to API documentation will not be generated. version: A string which will be included in the output to indicate the version of this documentation. (type: `dict` )
	outfileGenerator	Output filename factory. This is invoked with the intput filename and `ext` and the output document is serialized to the file with the name returned. (type: Callable of `str`, `str` returning `str` )
Returns	`None`

def _writeDocument(newFilename, clonedNode): (source)

Serialize the given node to XML into the named file.

Parameters	newFilename	The name of the file to which the XML will be written. If this is in a directory which does not exist, the directory will be created.
	clonedNode	The root DOM node which will be serialized.
Returns	`None`

API Documentation for Twisted, generated by pydoctor at 2011-10-27 16:27:37.