t.l.tree : module documentation

Part of twisted.lore View Source

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 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.

ParametersdocumentThe input document which contains all of the content to be presented. (type: A DOM Node or Document)
extThe extension to use when selecting an output file name. This replaces the extension of the input file name. (type: str)
ReturnsNone
def addMtime(document, fullpath): (source)
Set the last modified time of the given document.
ParametersdocumentThe output template which defines the presentation of the last modified time. (type: A DOM Node or Document)
fullpathThe file name from which to take the last modified time. (type: str)
ReturnsNone
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.

ReturnsThe fully qualified Python name. (type: str)
def fixAPI(document, url): (source)
Replace API references with links to API documentation.
ParametersdocumentThe input document which contains all of the content to be presented. (type: A DOM Node or Document)
urlA 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)
ReturnsNone
def fontifyPython(document): (source)
Syntax color any node in the given document which contains a Python source listing.
ParametersdocumentThe input document which contains all of the content to be presented. (type: A DOM Node or Document)
ReturnsNone
def fontifyPythonNode(node): (source)
Syntax color the given node containing Python source code.

The node must have a parent.

ReturnsNone
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.

ParametersdocumentThe document within which to make listing replacements. (type: A DOM Node or Document)
dirThe directory in which to find source files containing the referenced Python listings. (type: str)
ReturnsNone
def _makeLineNumbers(howMany): (source)
Return an element which will render line numbers for a source listing.
ParametershowManyThe number of lines in the source listing. (type: int)
ReturnsAn 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.

ParametersdocumentThe document within which to make listing replacements. (type: A DOM Node or Document)
dirThe directory in which to find source files containing the referenced HTML listings. (type: str)
ReturnsNone
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.

ParametersdocumentThe document within which to make listing replacements. (type: A DOM Node or Document)
dirThe directory in which to find source files containing the referenced text listings. (type: str)
ReturnsNone
def getHeaders(document): (source)
Return all H2 and H3 nodes in the given document.
Returns (type: list)
def generateToC(document): (source)
Create a table of contents for the given document.
Returnsa 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.

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.

ParametersdocumentThe input document which contains all of the content to be presented. (type: A DOM Node or Document)
ReturnsNone
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.

ParametersdocumentThe input document which contains all of the content to be presented. (type: A DOM Node or Document)
ReturnsNone
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)

ParametersdocumentThe input document which contains all of the content to be presented. (type: A DOM Node or Document)
ReturnsNone
def findNodeJustBefore(target, nodes): (source)
Find the last Element which is a sibling of target and is in nodes.
ParameterstargetA node the previous sibling of which to return.
nodesA list of nodes which might be the right node.
ReturnsThe 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.
ParametersentryThe node from which to begin traversal. This node itself is excluded from consideration. (type: A DOM Node)
ReturnsAll 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.

ParametersheaderThe 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)
ReturnsNone 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.

ParametersentryThe node for which to determine the section. (type: A DOM Node)
ReturnsThe 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.

ParametersdocumentThe input document which contains all of the content to be presented. (type: A DOM Node or Document)
filenameA 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: ???)
ReturnsNone
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.

ParameterstemplateThe output template which defines the presentation of the version information. (type: A DOM Node or Document)
indexFilenameThe address of the index document to which to link. If any False value, this function will remove all index-link nodes. (type: str)
ReturnsNone
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.

ParametersdocumentThe input document which contains all of the content to be presented. (type: A DOM Node or Document)
chapterNumberThe chapter number of this content in an overall document. (type: int)
ReturnsNone
def fixRelativeLinks(document, linkrel): (source)
Replace relative links in str and href attributes with links relative to linkrel.
ParametersdocumentThe output template. (type: A DOM Node or Document)
linkrelAn 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.

ParameterstemplateThe output template which defines the presentation of the version information. (type: A DOM Node or Document)
titleNodes from the input document defining its title. (type: list of DOM Nodes)
chapterNumberThe chapter number of this content in an overall document. If not applicable, any False value will result in this information being omitted. (type: int)
ReturnsNone
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.

ParameterstemplateThe output template which defines the presentation of the version information. (type: A DOM Node or Document)
authorsList of names and contact information for the authors of the input document. (type: list of two-tuples of str)
ReturnsNone
def setVersion(template, version): (source)
Add a version indicator to the given template.
ParameterstemplateThe output template which defines the presentation of the version information. (type: A DOM Node or Document)
versionThe version string to add to the template. (type: str)
ReturnsNone
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'.

Parametersindexignored, never passed.
Returns (type: str)
def munge(document, template, linkrel, dir, fullpath, ext, url, config, outfileGenerator=getOutputFileName): (source)
Mutate template until it resembles document.
ParametersdocumentThe input document which contains all of the content to be presented. (type: A DOM Node or Document)
templateThe template document which defines the desired presentation format of the content. (type: A DOM Node or Document)
linkrelAn prefix to apply to all relative links in src or href attributes in the input document when generating the output document. (type: str)
dirThe directory in which to search for source listing files. (type: str)
fullpathThe file name which contained the input document. (type: str)
extThe extension to use when selecting an output file name. This replaces the extension of the input file name. (type: str)
urlA 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)
configFurther 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)
outfileGeneratorOutput 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)
ReturnsNone
def parseFileAndReport(filename, _open=file): (source)
Parse and return the contents of the given lore XHTML document.
ParametersfilenameThe name of a file containing a lore XHTML document to load. (type: str)
ReturnsThe document contained in filename. (type: A DOM Document)
Raisesprocess.ProcessingFailureWhen 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.
ParametersfilenameThe path to the input file which will be processed. (type: str)
linkrelAn prefix to apply to all relative links in src or href attributes in the input document when generating the output document. (type: str)
extThe extension to use when selecting an output file name. This replaces the extension of the input file name. (type: str)
urlA 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)
templThe 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)
optionsFurther 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)
outfileGeneratorOutput 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)
ReturnsNone
def _writeDocument(newFilename, clonedNode): (source)
Serialize the given node to XML into the named file.
ParametersnewFilenameThe 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.
clonedNodeThe root DOM node which will be serialized.
ReturnsNone
API Documentation for Twisted, generated by pydoctor at 2012-12-26 12:18:15.