Hello community, here is the log from the commit of package python-twisted-lore checked in at Thu Aug 2 23:32:16 CEST 2007. -------- --- python-twisted-lore/python-twisted-lore.changes 2006-10-26 18:31:34.000000000 +0200 +++ /mounts/work_src_done/STABLE/python-twisted-lore/python-twisted-lore.changes 2007-08-02 17:07:18.000000000 +0200 @@ -1,0 +2,7 @@ +Thu Aug 2 17:06:48 CEST 2007 - jmatejek@suse.cz + +- update to 0.3.0 + * improved docstrings + * emitting a span with an index class to latex now works + +------------------------------------------------------------------- Old: ---- TwistedLore-0.2.0.tar.bz2 New: ---- TwistedLore-0.3.0.tar.bz2 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ Other differences: ------------------ ++++++ python-twisted-lore.spec ++++++ --- /var/tmp/diff_new_pack.Z16836/_old 2007-08-02 23:31:44.000000000 +0200 +++ /var/tmp/diff_new_pack.Z16836/_new 2007-08-02 23:31:44.000000000 +0200 @@ -1,7 +1,7 @@ # -# spec file for package python-twisted-lore (Version 0.2.0) +# spec file for package python-twisted-lore (Version 0.3.0) # -# Copyright (c) 2006 SUSE LINUX Products GmbH, Nuernberg, Germany. +# Copyright (c) 2007 SUSE LINUX Products GmbH, Nuernberg, Germany. # This file and all modifications and additions to the pristine # package are under the same license as the package itself. # @@ -13,7 +13,7 @@ Name: python-twisted-lore BuildRequires: python-devel python-twisted Summary: Twisted Lore -Version: 0.2.0 +Version: 0.3.0 Release: 1 %define tarname TwistedLore Source: %{tarname}-%{version}.tar.bz2 @@ -50,7 +50,11 @@ %defattr(-,root,root) %doc LICENSE README NEWS -%changelog -n python-twisted-lore +%changelog +* Thu Aug 02 2007 - jmatejek@suse.cz +- update to 0.3.0 + * improved docstrings + * emitting a span with an index class to latex now works * Thu Oct 26 2006 - jmatejek@suse.cz - update to 0.2.0 - upgrade to Twisted 2.4 install system ++++++ TwistedLore-0.2.0.tar.bz2 -> TwistedLore-0.3.0.tar.bz2 ++++++ diff -urN --exclude=CVS --exclude=.cvsignore --exclude=.svn --exclude=.svnignore old/TwistedLore-0.2.0/doc/examples/index.html new/TwistedLore-0.3.0/doc/examples/index.html --- old/TwistedLore-0.2.0/doc/examples/index.html 2006-05-25 03:09:00.000000000 +0200 +++ new/TwistedLore-0.3.0/doc/examples/index.html 2007-01-07 03:42:40.000000000 +0100 @@ -1,2 +1,2 @@ <?xml version="1.0"?><!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" - "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml" lang="en"><head><title>Twisted Documentation: Twisted Lore examples</title><link href="../howto/stylesheet.css" type="text/css" rel="stylesheet" /></head><body bgcolor="white"><h1 class="title">Twisted Lore examples</h1><div class="toc"><ol></ol></div><div class="content"><span></span><ul><li><a href="example.html">example.html</a></li><li><a href="slides-template.tpl">slides-template.tpl</a></li></ul></div><p><a href="../howto/index.html">Index</a></p><span class="version">Version: 0.2.0</span></body></html> \ No newline at end of file + "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml" lang="en"><head><title>Twisted Documentation: Twisted Lore examples</title><link href="../howto/stylesheet.css" type="text/css" rel="stylesheet" /></head><body bgcolor="white"><h1 class="title">Twisted Lore examples</h1><div class="toc"><ol></ol></div><div class="content"><span></span><ul><li><a href="example.html">example.html</a></li><li><a href="slides-template.tpl">slides-template.tpl</a></li></ul></div><p><a href="../howto/index.html">Index</a></p><span class="version">Version: 0.3.0</span></body></html> \ No newline at end of file diff -urN --exclude=CVS --exclude=.cvsignore --exclude=.svn --exclude=.svnignore old/TwistedLore-0.2.0/doc/howto/extend-lore.html new/TwistedLore-0.3.0/doc/howto/extend-lore.html --- old/TwistedLore-0.2.0/doc/howto/extend-lore.html 2006-05-25 03:08:57.000000000 +0200 +++ new/TwistedLore-0.3.0/doc/howto/extend-lore.html 2007-01-07 03:42:39.000000000 +0100 @@ -233,4 +233,4 @@ <span class="py-src-keyword">class</span> <span class="py-src-identifier">MyChapterLatexSpitter</span>(<span class="py-src-parameter">MySpitterMixin</span>, <span class="py-src-parameter">latex</span>.<span class="py-src-parameter">ChapterLatexSpitter</span>): <span class="py-src-keyword">pass</span> -</pre><div class="caption">spitters.py - <a href="listings/lore/spitters.py-2"><span class="filename">listings/lore/spitters.py-2</span></a></div></div></li></ul><h3>Creating New Outputs<a name="auto3"></a></h3><p><div class="doit">write some stuff</div></p><h2>Other Uses for Lore Extensions<a name="auto4"></a></h2><p><div class="doit">write some stuff</div></p><h3>Color-Code Programming Languages<a name="auto5"></a></h3><p><div class="doit">write some stuff</div></p><h3>Add New Structural Elements<a name="auto6"></a></h3><p><div class="doit">write some stuff</div></p><h3>Support New File Formats<a name="auto7"></a></h3><p><div class="doit">write some stuff</div></p></div><p><a href="../howto/index.html">Index</a></p><span class="version">Version: 0.2.0</span></body></html> \ No newline at end of file +</pre><div class="caption">spitters.py - <a href="listings/lore/spitters.py-2"><span class="filename">listings/lore/spitters.py-2</span></a></div></div></li></ul><h3>Creating New Outputs<a name="auto3"></a></h3><p><div class="doit">write some stuff</div></p><h2>Other Uses for Lore Extensions<a name="auto4"></a></h2><p><div class="doit">write some stuff</div></p><h3>Color-Code Programming Languages<a name="auto5"></a></h3><p><div class="doit">write some stuff</div></p><h3>Add New Structural Elements<a name="auto6"></a></h3><p><div class="doit">write some stuff</div></p><h3>Support New File Formats<a name="auto7"></a></h3><p><div class="doit">write some stuff</div></p></div><p><a href="../howto/index.html">Index</a></p><span class="version">Version: 0.3.0</span></body></html> \ No newline at end of file diff -urN --exclude=CVS --exclude=.cvsignore --exclude=.svn --exclude=.svnignore old/TwistedLore-0.2.0/doc/howto/index.html new/TwistedLore-0.3.0/doc/howto/index.html --- old/TwistedLore-0.2.0/doc/howto/index.html 2006-05-25 03:08:57.000000000 +0200 +++ new/TwistedLore-0.3.0/doc/howto/index.html 2007-01-07 03:42:39.000000000 +0100 @@ -1,2 +1,2 @@ <?xml version="1.0"?><!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" - "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml" lang="en"><head><title>Twisted Documentation: Twisted Lore Documentation</title><link href="../howto/stylesheet.css" type="text/css" rel="stylesheet" /></head><body bgcolor="white"><h1 class="title">Twisted Lore Documentation</h1><div class="toc"><ol></ol></div><div class="content"><span></span><ul class="toc"><li><a href="lore.html">Lore documentation system</a></li><li><a href="extend-lore.html">Extending Lore</a></li></ul></div><p><a href="../howto/index.html">Index</a></p><span class="version">Version: 0.2.0</span></body></html> \ No newline at end of file + "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml" lang="en"><head><title>Twisted Documentation: Twisted Lore Documentation</title><link href="../howto/stylesheet.css" type="text/css" rel="stylesheet" /></head><body bgcolor="white"><h1 class="title">Twisted Lore Documentation</h1><div class="toc"><ol></ol></div><div class="content"><span></span><ul class="toc"><li><a href="lore.html">Lore documentation system</a></li><li><a href="extend-lore.html">Extending Lore</a></li></ul></div><p><a href="../howto/index.html">Index</a></p><span class="version">Version: 0.3.0</span></body></html> \ No newline at end of file diff -urN --exclude=CVS --exclude=.cvsignore --exclude=.svn --exclude=.svnignore old/TwistedLore-0.2.0/doc/howto/lore.html new/TwistedLore-0.3.0/doc/howto/lore.html --- old/TwistedLore-0.2.0/doc/howto/lore.html 2006-05-25 03:08:59.000000000 +0200 +++ new/TwistedLore-0.3.0/doc/howto/lore.html 2007-01-07 03:42:40.000000000 +0100 @@ -133,4 +133,4 @@ </pre><p>This will generate compiler-style (file:line:column:message) warnings. It is possible to integrate these warnings into a smart editor such as EMACS, but it has not been done yet.</p><h2>Footnotes</h2><ol><li><a name="footnote-1"><span xmlns="http://www.w3.org/1999/xhtml" class="footnote">See also the -<code>admin/process-docs</code> script.</span></a></li></ol></div><p><a href="../howto/index.html">Index</a></p><span class="version">Version: 0.2.0</span></body></html> \ No newline at end of file +<code>admin/process-docs</code> script.</span></a></li></ol></div><p><a href="../howto/index.html">Index</a></p><span class="version">Version: 0.3.0</span></body></html> \ No newline at end of file diff -urN --exclude=CVS --exclude=.cvsignore --exclude=.svn --exclude=.svnignore old/TwistedLore-0.2.0/LICENSE new/TwistedLore-0.3.0/LICENSE --- old/TwistedLore-0.2.0/LICENSE 2006-04-18 04:43:54.000000000 +0200 +++ new/TwistedLore-0.3.0/LICENSE 2006-06-03 22:59:55.000000000 +0200 @@ -6,6 +6,7 @@ Bob Ippolito Canonical Limited Christopher Armstrong +David Reid Donovan Preston Eric Mangold Itamar Shtull-Trauring diff -urN --exclude=CVS --exclude=.cvsignore --exclude=.svn --exclude=.svnignore old/TwistedLore-0.2.0/NEWS new/TwistedLore-0.3.0/NEWS --- old/TwistedLore-0.2.0/NEWS 2006-05-24 16:52:43.000000000 +0200 +++ new/TwistedLore-0.3.0/NEWS 2007-01-06 23:24:26.000000000 +0100 @@ -1,3 +1,15 @@ +0.3.0 (2007-01-06) +================== + +Features +-------- + - Many docstrings were added to twisted.lore.tree (#2301) + +Fixes +----- + - Emitting a span with an index class to latex now works (#2134) + + 0.2.0 (2006-05-24) ================== diff -urN --exclude=CVS --exclude=.cvsignore --exclude=.svn --exclude=.svnignore old/TwistedLore-0.2.0/README new/TwistedLore-0.3.0/README --- old/TwistedLore-0.2.0/README 2006-05-23 14:57:55.000000000 +0200 +++ new/TwistedLore-0.3.0/README 2007-01-06 23:21:41.000000000 +0100 @@ -1,3 +1,3 @@ -Twisted Lore 0.2.0 +Twisted Lore 0.3.0 Twisted Lore depends on Twisted and Twisted Web. diff -urN --exclude=CVS --exclude=.cvsignore --exclude=.svn --exclude=.svnignore old/TwistedLore-0.2.0/twisted/lore/latex.py new/TwistedLore-0.3.0/twisted/lore/latex.py --- old/TwistedLore-0.2.0/twisted/lore/latex.py 2005-05-31 04:24:03.000000000 +0200 +++ new/TwistedLore-0.3.0/twisted/lore/latex.py 2006-10-09 22:36:38.000000000 +0200 @@ -284,7 +284,7 @@ def visitNode_span_index(self, node): self.writer('\\index{%s}\n' % node.getAttribute('value')) - spitter.visitNodeDefault(node) + self.visitNodeDefault(node) visitNode_h2 = visitNode_h3 = visitNode_h4 = visitNodeHeader Files old/TwistedLore-0.2.0/twisted/lore/scripts/__init__.pyc and new/TwistedLore-0.3.0/twisted/lore/scripts/__init__.pyc differ Files old/TwistedLore-0.2.0/twisted/lore/scripts/lore.pyc and new/TwistedLore-0.3.0/twisted/lore/scripts/lore.pyc differ diff -urN --exclude=CVS --exclude=.cvsignore --exclude=.svn --exclude=.svnignore old/TwistedLore-0.2.0/twisted/lore/test/test_lore.py new/TwistedLore-0.3.0/twisted/lore/test/test_lore.py --- old/TwistedLore-0.2.0/twisted/lore/test/test_lore.py 2004-12-26 15:16:12.000000000 +0100 +++ new/TwistedLore-0.3.0/twisted/lore/test/test_lore.py 2006-10-09 22:36:38.000000000 +0200 @@ -35,17 +35,20 @@ # __ put all of our test files someplace neat and tidy # +import os, shutil +from StringIO import StringIO + from twisted.trial import unittest -from twisted.lore.default import * from twisted.lore import tree, process, indexer, numberer, htmlbook, default +from twisted.lore.default import factory +from twisted.lore.latex import LatexSpitter from twisted.python.util import sibpath -from twisted.python import usage from twisted.lore.scripts import lore -import os, shutil +from twisted.web import microdom def sp(originalFileName): return sibpath(__file__, originalFileName) @@ -281,3 +284,20 @@ # VVV change to new, numbered files self.assertEqualFiles("lore_numbering_test_out.html", "lore_numbering_test.tns") self.assertEqualFiles("lore_numbering_test_out2.html", "lore_numbering_test2.tns") + + + +class LatexSpitterTestCase(unittest.TestCase): + """ + Tests for the Latex output plugin. + """ + def test_indexedSpan(self): + """ + Test processing of a span tag with an index class results in a latex + \\index directive the correct value. + """ + dom = microdom.parseString('<span class="index" value="name" />').documentElement + out = StringIO() + spitter = LatexSpitter(out.write) + spitter.visitNode(dom) + self.assertEqual(out.getvalue(), u'\\index{name}\n') diff -urN --exclude=CVS --exclude=.cvsignore --exclude=.svn --exclude=.svnignore old/TwistedLore-0.2.0/twisted/lore/tree.py new/TwistedLore-0.3.0/twisted/lore/tree.py --- old/TwistedLore-0.2.0/twisted/lore/tree.py 2005-03-22 10:23:09.000000000 +0100 +++ new/TwistedLore-0.3.0/twisted/lore/tree.py 2006-12-20 02:46:43.000000000 +0100 @@ -11,10 +11,29 @@ # relative links to html files def fixLinks(document, ext): + """ + Rewrite links to XHTML lore input documents so they point to lore XHTML + output documents. + + Any node with an C{href} attribute which does not contain a value starting + with C{http}, C{https}, C{ftp}, or C{mailto} and which does not have a + C{class} attribute of C{absolute} or which contains C{listing} and which + does point to an URL ending with C{html} will have that attribute value + rewritten so that the filename extension is C{ext} instead of C{html}. + + @type document: A DOM Node or Document + @param document: The input document which contains all of the content to be + presented. + + @type ext: C{str} + @param ext: The extension to use when selecting an output file name. This + replaces the extension of the input file name. + + @return: C{None} + """ supported_schemes=['http', 'https', 'ftp', 'mailto'] for node in domhelpers.findElementsWithAttribute(document, 'href'): href = node.getAttribute("href") - if urlparse.urlparse(href)[0] in supported_schemes: continue if node.getAttribute("class", "") == "absolute": @@ -32,17 +51,60 @@ node.setAttribute("href", fname + fext) + def addMtime(document, fullpath): + """ + Set the last modified time of the given document. + + @type document: A DOM Node or Document + @param document: The output template which defines the presentation of the + last modified time. + + @type fullpath: C{str} + @param fullpath: The file name from which to take the last modified time. + + @return: C{None} + """ for node in domhelpers.findElementsWithAttribute(document, "class","mtime"): node.appendChild(microdom.Text(time.ctime(os.path.getmtime(fullpath)))) + + def _getAPI(node): + """ + 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 C{base} + attribute, that attribute's value is prepended to the node's value, with + C{.} separating the two parts. + + @rtype: C{str} + @return: The fully qualified Python name. + """ base = "" if node.hasAttribute("base"): base = node.getAttribute("base") + "." return base+node.childNodes[0].nodeValue + + def fixAPI(document, url): + """ + Replace API references with links to API documentation. + + @type document: A DOM Node or Document + @param document: The input document which contains all of the content to be + presented. + + @type url: C{str} + @param 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. + + @return: C{None} + """ # API references for node in domhelpers.findElementsWithAttribute(document, "class", "API"): fullname = _getAPI(node) @@ -51,14 +113,33 @@ node.childNodes = [node2] node.removeAttribute('base') + + def fontifyPython(document): + """ + Syntax color any node in the given document which contains a Python source + listing. + + @type document: A DOM Node or Document + @param document: The input document which contains all of the content to be + presented. + + @return: C{None} + """ def matcher(node): return (node.nodeName == 'pre' and node.hasAttribute('class') and node.getAttribute('class') == 'python') for node in domhelpers.findElements(document, matcher): fontifyPythonNode(node) + + def fontifyPythonNode(node): + """ + Syntax color the given node containing Python source code. + + @return: C{None} + """ oldio = cStringIO.StringIO() latex.getLatexText(node, oldio.write, entities={'lt': '<', 'gt': '>', 'amp': '&'}) @@ -71,7 +152,29 @@ node.parentNode.replaceChild(newel, node) + def addPyListings(document, dir): + """ + Insert Python source listings into the given document from files in the + given directory based on C{py-listing} nodes. + + Any node in C{document} with a C{class} attribute set to C{py-listing} will + have source lines taken from the file named in that node's C{href} + attribute (searched for in C{dir}) inserted in place of that node. + + If a node has a C{skipLines} attribute, its value will be parsed as an + integer and that many lines will be skipped at the beginning of the source + file. + + @type document: A DOM Node or Document + @param document: The document within which to make listing replacements. + + @type dir: C{str} + @param dir: The directory in which to find source files containing the + referenced Python listings. + + @return: C{None} + """ for node in domhelpers.findElementsWithAttribute(document, "class", "py-listing"): filename = node.getAttribute("href") @@ -84,6 +187,7 @@ _replaceWithListing(node, val, filename, "py-listing") + def _replaceWithListing(node, val, filename, class_): captionTitle = domhelpers.getNodeText(node) if captionTitle == os.path.basename(filename): @@ -95,7 +199,25 @@ node.parentNode.replaceChild(newnode, node) + def addHTMLListings(document, dir): + """ + Insert HTML source listings into the given document from files in the given + directory based on C{html-listing} nodes. + + Any node in C{document} with a C{class} attribute set to C{html-listing} + will have source lines taken from the file named in that node's C{href} + attribute (searched for in C{dir}) inserted in place of that node. + + @type document: A DOM Node or Document + @param document: The document within which to make listing replacements. + + @type dir: C{str} + @param dir: The directory in which to find source files containing the + referenced HTML listings. + + @return: C{None} + """ for node in domhelpers.findElementsWithAttribute(document, "class", "html-listing"): filename = node.getAttribute("href") @@ -104,7 +226,25 @@ _replaceWithListing(node, val, filename, "html-listing") + def addPlainListings(document, dir): + """ + Insert text listings into the given document from files in the given + directory based on C{listing} nodes. + + Any node in C{document} with a C{class} attribute set to C{listing} will + have source lines taken from the file named in that node's C{href} + attribute (searched for in C{dir}) inserted in place of that node. + + @type document: A DOM Node or Document + @param document: The document within which to make listing replacements. + + @type dir: C{str} + @param dir: The directory in which to find source files containing the + referenced text listings. + + @return: C{None} + """ for node in domhelpers.findElementsWithAttribute(document, "class", "listing"): filename = node.getAttribute("href") @@ -113,11 +253,31 @@ _replaceWithListing(node, val, filename, "listing") + def getHeaders(document): - return domhelpers.findElements(document, - lambda n,m=re.compile('h[23]$').match:m(n.nodeName)) + """ + Return all H2 and H3 nodes in the given document. + + @type document: A DOM Node or Document + + @rtype: C{list} + """ + return domhelpers.findElements( + document, + lambda n, m=re.compile('h[23]$').match: m(n.nodeName)) + + def generateToC(document): + """ + Create a table of contents for the given document. + + @type document: A DOM Node or Document + + @rtype: A DOM Node + @return: a Node containing a table of contents based on the headers of the + given document. + """ toc, level, id = '\n<ol>\n', 0, 0 for element in getHeaders(document): elementLevel = int(element.tagName[1])-2 @@ -135,19 +295,59 @@ return microdom.parseString(toc).documentElement + def putInToC(document, toc): + """ + Insert the given table of contents into the given document. + + The node with C{class} attribute set to C{toc} has its children replaced + with C{toc}. + + @type document: A DOM Node or Document + @type toc: A DOM Node + """ tocOrig = domhelpers.findElementsWithAttribute(document, 'class', 'toc') if tocOrig: tocOrig= tocOrig[0] tocOrig.childNodes = [toc] + + def removeH1(document): + """ + Replace all C{h1} nodes in the given document with empty C{span} nodes. + + C{h1} nodes mark up document sections and the output template is given an + opportunity to present this information in a different way. + + @type document: A DOM Node or Document + @param document: The input document which contains all of the content to be + presented. + + @return: C{None} + """ h1 = domhelpers.findNodesNamed(document, 'h1') empty = microdom.Element('span') for node in h1: node.parentNode.replaceChild(empty, node) + + def footnotes(document): + """ + 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 C{class} attribute set to C{footnote}. + Footnote links are generated as superscript. Footnotes are collected in a + C{ol} node at the end of the document. + + @type document: A DOM Node or Document + @param document: The input document which contains all of the content to be + presented. + + @return: C{None} + """ footnotes = domhelpers.findElementsWithAttribute(document, "class", "footnote") if not footnotes: @@ -172,22 +372,67 @@ body.childNodes.append(header) body.childNodes.append(footnoteElement) + + def notes(document): + """ + Find notes in the given document and mark them up as such. + + A note is any node with a C{class} attribute set to C{note}. + + (I think this is a very stupid feature. When I found it I actually + exclaimed out loud. -exarkun) + + @type document: A DOM Node or Document + @param document: The input document which contains all of the content to be + presented. + + @return: C{None} + """ notes = domhelpers.findElementsWithAttribute(document, "class", "note") notePrefix = microdom.parseString('<strong>Note: </strong>').documentElement for note in notes: note.childNodes.insert(0, notePrefix) + + def compareMarkPos(a, b): + """ + Perform in every way identically to L{cmp} for valid inputs. + + XXX - replace this with L{cmp} + """ linecmp = cmp(a[0], b[0]) if linecmp: return linecmp return cmp(a[1], b[1]) -def comparePosition(a, b): - return compareMarkPos(a._markpos, b._markpos) + + +def comparePosition(firstElement, secondElement): + """ + Compare the two elements given by their position in the document or + documents they were parsed from. + + @type firstElement: C{twisted.web.microdom.Element} + @type secondElement: C{twisted.web.microdom.Element} + + @return: C{-1}, C{0}, or C{1}, with the same meanings as the return value + of L{cmp}. + """ + return compareMarkPos(firstElement._markpos, secondElement._markpos) + + def findNodeJustBefore(target, nodes): + """ + Find the node in C{nodes} which appeared immediately before C{target} in + the input document. + + @type target: L{twisted.web.microdom.Element} + @type nodes: C{list} of L{twisted.web.microdom.Element} + @return: An element from C{nodes} + """ result = None for node in nodes: if comparePosition(target, node) < 0: @@ -195,25 +440,86 @@ result = node return result + + def getFirstAncestorWithSectionHeader(entry): - """Go up ancestors until one with at least one <h2> is found, then return the <h2> nodes""" + """ + Visit the ancestors of C{entry} until one with at least one C{h2} child + node is found, then return all of that node's C{h2} child nodes. + + @type entry: A DOM Node + @param entry: The node from which to begin traversal. This node itself is + excluded from consideration. + + @rtype: C{list} of DOM Nodes + @return: All C{h2} nodes of the ultimately selected parent node. + """ for a in domhelpers.getParents(entry)[1:]: headers = domhelpers.findNodesNamed(a, "h2") if len(headers) > 0: return headers return [] + + def getSectionNumber(header): + """ + Retrieve the section number of the given node. + + @type header: A DOM Node or L{None} + @param header: The section from which to extract a number. The section + number is the value of this node's first child. + + @return: C{None} or a C{str} giving the section number. + """ if not header: return None return header.childNodes[0].value.strip() + + def getSectionReference(entry): + """ + 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. + + @type entry: A DOM Node + @param entry: The node for which to determine the section. + + @rtype: C{str} + @return: The section number, as returned by C{getSectionNumber} of the + first ancestor of C{entry} which defines a section, as determined by + L{getFirstAncestorWithSectionHeader}. + """ headers = getFirstAncestorWithSectionHeader(entry) myHeader = findNodeJustBefore(entry, headers) return getSectionNumber(myHeader) + + def index(document, filename, chapterReference): + """ + 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 C{class} attribute set to C{index} is considered an index + entry. + + @type document: A DOM Node or Document + @param document: The input document which contains all of the content to be + presented. + + @type filename: C{str} + @param 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 chapterReference: ??? + @param chapterReference: ??? + + @return: C{None} + """ entries = domhelpers.findElementsWithAttribute(document, "class", "index") if not entries: return @@ -230,7 +536,25 @@ entry.nodeName = entry.tagName = entry.endTagName = 'a' entry.attributes = InsensitiveDict({'name': anchor}) + + def setIndexLink(template, indexFilename): + """ + Insert a link to an index document. + + Any node with a C{class} attribute set to C{index-link} will have its tag + name changed to C{a} and its C{href} attribute set to C{indexFilename}. + + @type template: A DOM Node or Document + @param template: The output template which defines the presentation of the + version information. + + @type indexFilename: C{str} + @param indexFilename: The address of the index document to which to link. + If any C{False} value, this function will do nothing. + + @return: C{None} + """ if not indexFilename: return indexLinks = domhelpers.findElementsWithAttribute(template, "class", "index-link") @@ -238,20 +562,75 @@ link.nodeName = link.tagName = link.endTagName = 'a' link.attributes = InsensitiveDict({'href': indexFilename}) + + def numberDocument(document, chapterNumber): + """ + Number the sections of the given document. + + A dot-separated chapter, section number is added to the beginning of each + section, as defined by C{h2} nodes. + + @type document: A DOM Node or Document + @param document: The input document which contains all of the content to be + presented. + + @type chapterNumber: C{int} + @param chapterNumber: The chapter number of this content in an overall + document. + + @return: C{None} + """ i = 1 for node in domhelpers.findNodesNamed(document, "h2"): node.childNodes = [microdom.Text("%s.%d " % (chapterNumber, i))] + node.childNodes i += 1 + + def fixRelativeLinks(document, linkrel): + """ + Replace relative links in C{str} and C{href} attributes with links relative + to C{linkrel}. + + @type document: A DOM Node or Document + @param document: The output template. + + @type linkrel: C{str} + @param linkrel: An prefix to apply to all relative links in C{src} or + C{href} attributes in the input document when generating the output + document. + """ for attr in 'src', 'href': for node in domhelpers.findElementsWithAttribute(document, attr): href = node.getAttribute(attr) if not href.startswith('http') and not href.startswith('/'): node.setAttribute(attr, linkrel+node.getAttribute(attr)) + + def setTitle(template, title, chapterNumber): + """ + Add title and chapter number information to the template document. + + The title is added to the end of the first C{title} tag and the end of the + first tag with a C{class} attribute set to C{title}. If specified, the + chapter is inserted before the title. + + @type template: A DOM Node or Document + @param template: The output template which defines the presentation of the + version information. + + @type title: C{list} of DOM Nodes + @param title: Nodes from the input document defining its title. + + @type chapterNumber: C{int} + @param chapterNumber: The chapter number of this content in an overall + document. If not applicable, any C{False} value will result in this + information being omitted. + + @return: C{None} + """ for nodeList in (domhelpers.findNodesNamed(template, "title"), domhelpers.findElementsWithAttribute(template, "class", 'title')): @@ -260,7 +639,26 @@ nodeList[0].childNodes.append(microdom.Text('%s. ' % chapterNumber)) nodeList[0].childNodes.extend(title) + + def setAuthors(template, authors): + """ + Add author information to the template document. + + Names and contact information for authors are added to each node with a + C{class} attribute set to C{authors} and to the template head as C{link} + nodes. + + @type template: A DOM Node or Document + @param template: The output template which defines the presentation of the + version information. + + @type authors: C{list} of two-tuples of C{str} + @param authors: List of names and contact information for the authors of + the input document. + + @return: C{None} + """ # First, similarly to setTitle, insert text into an <div class="authors"> text = '' for name, href in authors: @@ -277,9 +675,9 @@ childNodes = microdom.parseString('<span>' + text +'</span>').childNodes - for node in domhelpers.findElementsWithAttribute(template, + for node in domhelpers.findElementsWithAttribute(template, "class", 'authors'): - node.childNodes.extend(childNodes) + node.childNodes.extend(childNodes) # Second, add appropriate tags to the <head>. head = domhelpers.findNodesNamed(template, 'head')[0] @@ -288,16 +686,95 @@ for name, href in authors] head.childNodes.extend(authors) + + def setVersion(template, version): + """ + Add a version indicator to the given template. + + @type template: A DOM Node or Document + @param template: The output template which defines the presentation of the + version information. + + @type version: C{str} + @param version: The version string to add to the template. + + @return: C{None} + """ for node in domhelpers.findElementsWithAttribute(template, "class", "version"): node.appendChild(microdom.Text(version)) - + + def getOutputFileName(originalFileName, outputExtension, index=None): + """ + Return a filename which is the same as C{originalFileName} except for the + extension, which is replaced with C{outputExtension}. + + For example, if C{originalFileName} is C{'/foo/bar.baz'} and + C{outputExtension} is C{'quux'}, the return value will be + C{'/foo/bar.quux'}. + + @type originalFileName: C{str} + @type outputExtension: C{stR} + @param index: ignored, never passed. + @rtype: C{str} + """ return os.path.splitext(originalFileName)[0]+outputExtension + + def munge(document, template, linkrel, dir, fullpath, ext, url, config, outfileGenerator=getOutputFileName): + """ + Mutate C{template} until it resembles C{document}. + + @type document: A DOM Node or Document + @param document: The input document which contains all of the content to be + presented. + + @type template: A DOM Node or Document + @param template: The template document which defines the desired + presentation format of the content. + + @type linkrel: C{str} + @param linkrel: An prefix to apply to all relative links in C{src} or + C{href} attributes in the input document when generating the output + document. + + @type dir: C{str} + @param dir: The directory in which to search for source listing files. + + @type fullpath: C{str} + @param fullpath: The file name which contained the input document. + + @type ext: C{str} + @param ext: The extension to use when selecting an output file name. This + replaces the extension of the input file name. + + @type url: C{str} + @param 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 config: C{dict} + @param 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 outfileGenerator: Callable of C{str}, C{str} returning C{str} + @param outfileGenerator: Output filename factory. This is invoked with the + intput filename and C{ext} and the output document is serialized to the + file with the name returned. + + @return: C{None} + """ fixRelativeLinks(template, linkrel) addMtime(template, fullpath) removeH1(document) @@ -337,6 +814,19 @@ def parseFileAndReport(filename): + """ + Parse and return the contents of the given lore XHTML document. + + @type filename: C{str} + @param filename: The name of a file containing a lore XHTML document to + load. + + @raise process.ProcessingFailure: When the contents of the specified file + cannot be parsed. + + @rtype: A DOM Document + @return: The document contained in C{filename}. + """ try: return microdom.parse(open(filename)) except microdom.MismatchedTags, e: @@ -357,6 +847,48 @@ os.makedirs(dirname) def doFile(filename, linkrel, ext, url, templ, options={}, outfileGenerator=getOutputFileName): + """ + Process the input document at C{filename} and write an output document. + + @type filename: C{str} + @param filename: The path to the input file which will be processed. + + @type linkrel: C{str} + @param linkrel: An prefix to apply to all relative links in C{src} or + C{href} attributes in the input document when generating the output + document. + + @type ext: C{str} + @param ext: The extension to use when selecting an output file name. This + replaces the extension of the input file name. + + @type url: C{str} + @param 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 templ: A DOM Node or Document + @param templ: The template on which the output document will be based. + This is mutated and then serialized to the output file. + + @type options: C{dict} + @param 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 outfileGenerator: Callable of C{str}, C{str} returning C{str} + @param outfileGenerator: Output filename factory. This is invoked with the + intput filename and C{ext} and the output document is serialized to the + file with the name returned. + + @return: C{None} + """ doc = parseFileAndReport(filename) clonedNode = templ.cloneNode(1) munge(doc, clonedNode, linkrel, os.path.dirname(filename), filename, ext, diff -urN --exclude=CVS --exclude=.cvsignore --exclude=.svn --exclude=.svnignore old/TwistedLore-0.2.0/twisted/lore/_version.py new/TwistedLore-0.3.0/twisted/lore/_version.py --- old/TwistedLore-0.2.0/twisted/lore/_version.py 2006-05-23 14:57:55.000000000 +0200 +++ new/TwistedLore-0.3.0/twisted/lore/_version.py 2007-01-06 23:21:41.000000000 +0100 @@ -1,3 +1,3 @@ # This is an auto-generated file. Use admin/change-versions to update. from twisted.python import versions -version = versions.Version(__name__[:__name__.rfind('.')], 0, 2, 0) +version = versions.Version(__name__[:__name__.rfind('.')], 0, 3, 0) ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ Remember to have fun... --------------------------------------------------------------------- To unsubscribe, e-mail: opensuse-commit+unsubscribe@opensuse.org For additional commands, e-mail: opensuse-commit+help@opensuse.org