Mailinglist Archive: opensuse-commit (2092 mails)
| < Previous | Next > |
commit python-twisted-lore
- From: root@xxxxxxxxxxxxxxx (h_root)
- Date: Thu, 02 Aug 2007 23:32:16 +0200
- Message-id: <20070802213216.A45006781B8@xxxxxxxxxxxxxxx>
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@xxxxxxx
+
+- 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@xxxxxxx
+- update to 0.3.0
+ * improved docstrings
+ * emitting a span with an index class to latex now works
* Thu Oct 26 2006 - jmatejek@xxxxxxx
- 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 <link rel="author" ...> 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@xxxxxxxxxxxx
For additional commands, e-mail: opensuse-commit+help@xxxxxxxxxxxx
| < Previous | Next > |