1. Martin von Löwis
  2. xist-3k

Commits

Walter Dörwald  committed 966d4e7 Merge

Automated merge with ssh://hg@warrah/LivingLogic.Python.xist

  • Participants
  • Parent commits e358a06, b38693f
  • Branches default

Comments (0)

Files changed (8)

File INSTALL.rst

View file
 your trees using any of the browsers provided by IPython's `ipipe module`_.
 
 	.. _IPython: http://ipython.scipy.org/
-	.. _ipipe module: http://projects.scipy.org/ipython/ipython/wiki/UsingIPipe
+	.. _ipipe module: http://ipython.scipy.org/moin/UsingIPipe
 
 You can specify which format gets used by changing the value of the
 ``defaultpresenter`` variable in the module :mod:`ll.xist.presenters`::

File docs/XIST_Advanced.xml

View file
 
 <section><h>Conversion targets</h>
 
-<p>The <arg>converter</arg> argument passed to the <meth>convert</meth>
+<p>The <var>converter</var> argument passed to the <meth>convert</meth>
 method has an attribute <lit>target</lit> which is a module or pool and
 specifies the target namespace to which <self/> should be converted.</p>
 
 </example>
 
 <p>The default target for conversion is <mod>ll.xist.ns.html</mod>.
-Other targets can be specified via the <arg>target</arg> argument in the
+Other targets can be specified via the <var>target</var> argument in the
 <class>Converter</class> constructor or the <meth>conv</meth> method:</p>
 
 <tty>

File docs/XIST_Howto.xml

View file
 <prog>
 __init__(self, *content, **attrs)
 </prog>
-<p>Positional arguments (i.e. items in <arg>content</arg>)
+<p>Positional arguments (i.e. items in <var>content</var>)
 will be the child nodes of the element node. Keyword arguments will be attributes.
 You can pass most of Python's builtin types to such a constructor.
 Strings (<class>str</class> and <class>unicode</class>) and integers
 provides several functions:</p>
 <dl>
 <dt><lit>parsestring(data, base=None, encoding=None, **builderargs)</lit></dt>
-<dd>Parse the string <arg>data</arg> into an &xist; tree.</dd>
+<dd>Parse the string <var>data</var> into an &xist; tree.</dd>
 <dt><lit>parseiter(iterable, base=None, encoding=None, **builderargs)</lit></dt>
-<dd>Parse the input from the iterable <arg>iterable</arg> (which must produce the
+<dd>Parse the input from the iterable <var>iterable</var> (which must produce the
 input in chunks of bytes) into an &xist; tree.</dd>
 <dt><lit>parsestream(stream, base=None, encoding=None, bufsize=8192, **builderargs)</lit></dt>
-<dd>Parse &xml; from the stream <arg>stream</arg> into an &xist; tree.</dd>
+<dd>Parse &xml; from the stream <var>stream</var> into an &xist; tree.</dd>
 <dt><lit>parsefile(filename, base=None, encoding=None, bufsize=8192, **builderargs)</lit></dt>
-<dd>Parse &xml; input from the file named <arg>filename</arg>.</dd>
+<dd>Parse &xml; input from the file named <var>filename</var>.</dd>
 <dt><lit>parseurl(name, base=None, encoding=None, bufsize=8192, headers=None, data=None, **builderargs)</lit></dt>
-<dd>Parse &xml; input from the &url; <arg>name</arg> into an &xist; tree.</dd>
+<dd>Parse &xml; input from the &url; <var>name</var> into an &xist; tree.</dd>
 <dt><lit>parseetree(tree, base=None, **builderargs)</lit></dt>
-<dd>Parse &xml; input from the object <arg>tree</arg> which must support the
+<dd>Parse &xml; input from the object <var>tree</var> which must support the
 <a href="http://effbot.org/zone/element-index.htm">ElementTree</a> &api;.</dd>
 </dl>
 <p>For example, parsing a string can be done like this:</p>
 <example><h>Parsing a string</h>
-<prog>
+<prog><![CDATA[
 from ll.xist import parsers
 from ll.xist.ns import html
 
-node = parsers.parsestring(
-	"&lt;p&gt;Hello &lt;a href='http://www.python.org/'&gt;Python&lt;/a&gt; world!&lt;/p&gt;"
-)
-</prog>
+node = parsers.parsestring("<p>Hello <a href='http://www.python.org/'>Python</a> world!</p>")
+]]></prog>
 </example>
 
 <p>For further info about the arguments to the parsing functions, see the
 <p><pyref module="ll.xist.xsc" class="Node" method="conv"><meth>conv</meth></pyref> simply
 calls
 <pyref module="ll.xist.xsc" class="Node" method="convert"><meth>convert</meth></pyref>
-with a default <pyref module="ll.xist.converters" class="Converter"><arg>converter</arg></pyref>
+with a default <pyref module="ll.xist.converters" class="Converter"><var>converter</var></pyref>
 argument. We'll come to converters in a minute.
 <pyref module="ll.xist.xsc" class="Node" method="bytes"><meth>bytes</meth></pyref>
 is a method that converts the node to a byte string. This method will be explained
 <p>You can pass the following arguments to the
 <pyref module="ll.xist.converters" class="Converter"><class>Converter</class></pyref> constructor:</p>
 <dl>
-<dt><arg>root</arg></dt><dd><arg>root</arg> (which defaults to <lit>None</lit>) is the root &url;
+<dt><var>root</var></dt><dd><var>root</var> (which defaults to <lit>None</lit>) is the root &url;
 for the conversion process. When you want to resolve a link in some of your own <meth>convert</meth> methods,
 the &url; must be interpreted relative to this root &url; (You can use
 <pyref module="ll.xist.xsc" class="URLAttr" method="forInput"><meth>URLAttr.forInput</meth></pyref>
 for that).</dd>
-<dt><arg>mode</arg></dt><dd><arg>mode</arg> (which defaults to <lit>None</lit>) works the same way
+<dt><var>mode</var></dt><dd><var>mode</var> (which defaults to <lit>None</lit>) works the same way
 as modes in &xslt;. You can use this for implementing different conversion modes.</dd>
-<dt><arg>stage</arg></dt><dd><arg>stage</arg> (which defaults to <lit>"deliver"</lit>)
+<dt><var>stage</var></dt><dd><var>stage</var> (which defaults to <lit>"deliver"</lit>)
 allows you to implement multi stage conversion: Suppose that you want to deliver a dynamically
 constructed web page with &xist; that contains results from a database query and the current time.
 The data in the database changes infrequently, so it doesn't make sense to do the query on
 every request. The query is done every few minutes and the resulting &html; tree is
 stored in the servlet (using any of the available Python servlet technologies).
-For this conversion the <arg>stage</arg> would be <lit>"cache"</lit> and your database &xml;
-element would do the query when <lit><arg>stage</arg>=="cache"</lit>. Your time display element
-would do the conversion when <lit><arg>stage</arg>=="deliver"</lit> and simply returns itself
-when <lit><arg>stage</arg>=="cache"</lit>, so it would still be part of the cached &xml; tree
+For this conversion the <var>stage</var> would be <lit>"cache"</lit> and your database &xml;
+element would do the query when <lit><var>stage</var>=="cache"</lit>. Your time display element
+would do the conversion when <lit><var>stage</var>=="deliver"</lit> and simply returns itself
+when <lit><var>stage</var>=="cache"</lit>, so it would still be part of the cached &xml; tree
 and would be converted to &html; on every request.</dd>
-<dt><arg>target</arg></dt><dd><arg>target</arg> (which defaults to
+<dt><var>target</var></dt><dd><var>target</var> (which defaults to
 <pyref module="ll.xist.ns.html"><mod>ll.xist.ns.html</mod></pyref>) specifies what the output should be.
 Values must be <pyref module="ll.xist.xsc" class="Namespace">namespace subclasses</pyref>
 (see below for an explanation of namespaces).</dd>
-<dt><arg>lang</arg></dt><dd><p><arg>lang</arg> (which defaults to <lit>None</lit>) is the language
+<dt><var>lang</var></dt><dd><p><var>lang</var> (which defaults to <lit>None</lit>) is the language
 in which the result tree should be. This can be used in the <meth>convert</meth> method
 to implement different conversions for different languages, e.g.:</p>
 <prog>
 an instance of <pyref module="ll.xist.publishers" class="Publisher"><class>ll.xist.publisher.Publisher</class></pyref>.</p>
 
 <section><h>Specifying an encoding</h>
-<p>You can specify the encoding with the parameter <arg>encoding</arg>
+<p>You can specify the encoding with the parameter <var>encoding</var>
 (with the encoding specified in an &xml; declaration being the default, if there
 is no such declaration <lit>"utf-8"</lit> is used). Unencodable characters will
 be escaped with character references when possible (i.e. inside text nodes, for
 </section>
 
 <section><h>&html; compatibility</h>
-<p>Another useful parameter is <arg>xhtml</arg>,
+<p>Another useful parameter is <var>xhtml</var>,
 it specifies whether you want pure &html; or &xhtml; as output:</p>
 
 <dl>
 <section><h>Namespaces</h>
 
 <p>By default &xist; doesn't output any namespace declarations. The simplest
-way to change that, is to pass <lit>True</lit> for the <arg>prefixdefault</arg>
+way to change that, is to pass <lit>True</lit> for the <var>prefixdefault</var>
 argument when publishing:</p>
 
 <example><h>Publishing namespace info</h>
 </html>]]></prog>
 
 <p>When elements from more than one namespace are present in the tree,
-<arg>prefixdefault</arg> is unreliable. The first namespace encountered will
-get the prefix specified by <arg>prefixdefault</arg>, all others will get a
+<var>prefixdefault</var> is unreliable. The first namespace encountered will
+get the prefix specified by <var>prefixdefault</var>, all others will get a
 different prefix. &xist; will never use the same prefix for different namespaces.
 &xist; will also refuse to use an empty prefix for global attributes:</p>
 
 </html>]]>
 </prog>
 
-<p>In the case of multiple namespaces you can use the <arg>prefixes</arg>
+<p>In the case of multiple namespaces you can use the <var>prefixes</var>
 argument to specify an explicit prefix for each namespace. So we could change
 the publishing statement from our example above to:</p>
 
 </prog>
 
 <p>Finally it's possible to suppress output of namespace declarations
-for certain namespaces by using the <arg>hidexmlns</arg> attribute:</p>
+for certain namespaces by using the <var>hidexmlns</var> attribute:</p>
 </section>
 
 <prog>

File docs/XIST_Misc.xml

View file
 reverted for publishing. In most cases the base &url; should be a
 <lit>root</lit> &url; when you parse local files.</li>
 <li>When you parse remote web pages you can either
-omit the <arg>base</arg> argument, so it will default to the
+omit the <var>base</var> argument, so it will default to the
 &url; being parsing, so that links, images, etc. on the page
 will still point back to their original location, or you
 might want to use the empty &url; <lit>URL()</lit> as the
 </prog>
 <p>the following will happen: The &url; <lit>#top</lit>
 will be parsed as <lit>root:spam.htmlxsc#top</lit>. After
-conversion this will be written to <filename>spam.html</filename>
+conversion this will be written to <file>spam.html</file>
 relative to the &url; <lit>root:spam.html</lit>, which results
 in <lit>spam.html#top</lit>, which works, but is not what you
 want.</p>
 </example>
 <p>This will print:</p>
 <example>
-<tty>
-&lt;html&gt;
-	&lt;head&gt;
-		&lt;title&gt;foo&lt;/title&gt;
-	&lt;/head&gt;
-	&lt;body&gt;
-		&lt;div&gt;
-			&lt;h1&gt;The &lt;em&gt;foo&lt;/em&gt; page!&lt;/h1&gt;
-			&lt;p&gt;Welcome to the &lt;em&gt;foo&lt;/em&gt; page.&lt;/p&gt;
-		&lt;/div&gt;
-	&lt;/body&gt;
-&lt;/html&gt;
-</tty>
+<tty><![CDATA[
+<html>
+	<head>
+		<title>foo</title>
+	</head>
+	<body>
+		<div>
+			<h1>The <em>foo</em> page!</h1>
+			<p>Welcome to the <em>foo</em> page.</p>
+		</div>
+	</body>
+</html>
+]]></tty>
 </example>
 <p>Element content will only be modified if it doesn't contain
 <class>Text</class> nodes, so mixed content will not be touched.</p>
 for a <pyref module="ll.xist.ns.code" class="pyeval"><lit>pyeval</lit></pyref> processing instruction is whatever the
 Python code in the content returns. The processing instruction content is treated as the body
 of a function, so you can put multiple return statements there.
-The converter is available as the parameter <arg>converter</arg> inside
+The converter is available as the parameter <var>converter</var> inside
 the processing instruction. For example, consider the following &xml; file:</p>
 
 <prog>

File docs/XIST_Searching.xml

View file
 
 <section><h>&css; selectors</h>
 
-<p>It's also possible to use &css; selectors as walk filter. The module
+<p>It's also possible to use &css; selectors as walk filters. The module
 <pyref module="ll.xist.css"><mod>ll.xist.css</mod></pyref> provides a
 function <func>selector</func> that turns a &css; selector expression
 into a walk filter:</p>

File src/ll/_misc.c

View file
 /*
-** Copyright 2007 by LivingLogic AG, Bayreuth, Germany.
-** Copyright 2007 by Walter D�rwald
+** Copyright 2007-2008 by LivingLogic AG, Bayreuth, Germany.
+** Copyright 2007-2008 by Walter D�rwald
 **
 ** All Rights Reserved
 **
 
 
 PyDoc_STRVAR(item_doc,
-"Returns the <arg>index</arg>'th element from the iterable. <arg>index</arg> may be\n\
+"Returns the :var:`index`'th element from the iterable. :var:`index` may be\n\
 negative to count from the end. E.g. 0 returns the first element produced by\n\
-the iterator, 1 the second, -1 the last one etc. If <arg>index</arg> is negative\n\
+the iterator, 1 the second, -1 the last one etc. If :var:`index` is negative\n\
 the iterator will be completely exhausted, if it's positive it will be\n\
-exhausted up to the <arg>index</arg>'th element. If the iterator doesn't produce\n\
-that many elements <class>IndexError</class> will be raised, except when\n\
-<arg>default</arg> is given, in which case <arg>default</arg> will be returned.");
+exhausted up to the :var:`index`'th element. If the iterator doesn't produce\n\
+that many elements :exc:`IndexError` will be raised, except when\n\
+:var:`default` is given, in which case :var:`default` will be returned.");
 
 
 static PyObject *first(PyObject *self, PyObject *args)
 
 
 PyDoc_STRVAR(first_doc,
-"Returns the first element from the iterable. If the iterator doesn't produce\n\
-any elements <class>IndexError</class> will be raised, except when\n\
-<arg>default</arg> is given, in which case <arg>default</arg> will be returned.");
+"Return the first element from the iterable. If the iterator doesn't produce\n\
+any elements :exc:`IndexError` will be raised, except when :var:`default` is\n\
+given, in which case :var:`default` will be returned.");
 
 
 static PyObject *last(PyObject *self, PyObject *args)
 
 
 PyDoc_STRVAR(last_doc,
-"Returns the last element from the iterable. If the iterator doesn't produce\n\
-any elements <class>IndexError</class> will be raised, except when\n\
-<arg>default</arg> is given, in which case <arg>default</arg> will be returned.");
+"Return the last element from the iterable. If the iterator doesn't produce\n\
+any elements :exc:`IndexError` will be raised, except when :var:`default` is\n\
+given, in which case :var:`default` will be returned.");
 
 
 static PyObject *count(PyObject *self, PyObject *iterable)
 };
 
 static char module__doc__[] =
-"This module contains the functions item(), first(), last() and count().";
+"This module contains the functions :func:`item` :func:`first`, :func:`last` and
+:func:`count`.";
 
 
 PyMODINIT_FUNC

File src/ll/misc.py

View file
 from ll._misc import *
 
 
-__docformat__ = "xist"
+__docformat__ = "reStructuredText"
 
 
 def notimplemented(function):

File src/ll/sisyphus.py

View file
 ## See __init__.py for the license
 
 
-r"""
-<p><mod>ll.sisyphus</mod> simplifies running Python stuff as cron jobs.</p>
+"""
+:mod:`ll.sisyphus` simplifies running Python stuff as cron jobs.
 
-<p>There will be no more than one sisyphus job of a certain name
-running at every given time. When the job is already running
-and a second is started, the second one will quit immediately
-if the first one hasn't exceeded its maximum allowed lifetime
-yet. If it has exceeded the allowed lifetime the first job
-will be killed and the second will start running.</p>
+There will be no more than one sisyphus job of a certain name running at every
+given time. When the job is already running and a second is started, the second
+one will quit immediately if the first one hasn't exceeded its maximum allowed
+lifetime yet. If it has exceeded the allowed lifetime the first job
+will be killed and the second will start running.
 
-<p>In addition to that, logging features are provided.</p>
+In addition to that, logging features are provided.
 
-<p>To use this module, you must derive your own
-class from <pyref class="Job"><class>Job</class></pyref> and implement
-the <pyref class="Job" method="execute"><meth>execute</meth></pyref> method.</p>
+To use this module, you must derive your own class from :class:`Job` and
+implement the :meth:`execute` method.
 
-<p>The job announces its presence (and its process id) in a file that
-is stored in the <dirname>~/run</dirname> directory. Logs will be created in the
-<dirname>~/log</dirname> directory (This can be changes by deriving new subclasses).</p>
+The job announces its presence (and its process id) in a file that is stored in
+the :dir:`~/run` directory. Logs will be created in the :dir:`~/log` directory
+(This can be changes by deriving new subclasses and overwriting the appropriate
+class attribute).
 
-<p>There are three log files:</p>
-<dl>
-<dt><filename>~/log/<rep>jobname</rep>_progress.log</filename></dt>
-<dd>The progress of one job execution is logged here.
-This log file will be truncated at the start of every execution,
-so you can be rather verbose.
-Use the <pyref class="Job" method="logProgress"><meth>logProgress</meth></pyref>
-method for writing to this log file.</dd>
-<dt><filename>~/log/<rep>jobname</rep>_loop.log</filename></dt>
-<dd>One log line may be appended to the log after every job execution.
-Use the <pyref class="Job" method="logLoop"><meth>logLoop</meth></pyref>
-method for this.</dd>
-<dt><filename>~/log/<rep>jobname</rep>_error.log</filename></dt>
-<dd>Here exceptions happening during the execution of a job
-will be logged. This is done via the <pyref class="Job" method="logError"><meth>logError</meth></pyref>
-method with can be used for reporting other exception conditions apart
-from exceptions.</dd>
-</dl>
+There are three log files:
 
-<p>To execute a job, use the function
-<pyref function="execute"><func>execute</func></pyref>.</p>
+	:file:`~/log/jobname_progress.log`
+		The progress of one job execution is logged here. This log file will be
+		truncated at the start of every execution, so you can be rather verbose.
+		Use the :meth:`logProgress` method for writing to this log file.
 
-<section><h>Example</h>
-<p>The following example illustrates the use of this module:</p>
-<example>
-<h>Complete example showing the use of sisyphus</h>
-<prog>
-#!/usr/bin/env python
+	:file:`~/log/jobname_loop.log`
+		One log line may be appended to the log after every job execution.
+		:meth:`logLoop` method for this.
 
-import os
-import urllib
-from ll import sisyphus
+	:file:`~/log/jobname_error.log`
+		Here exceptions happening during the execution of a job will be logged.
+		This is done via the :meth:`logError` method with can be used for
+		reporting other exception conditions apart from exceptions.
 
-class Fetch(sisyphus.Job):
-	"savely fetches an HTML file and saves it to a local file."
+To execute a job, use the module level function :func:`execute`.
 
-	def __init__(self):
-		sisyphus.Job.__init__(self, 180, name="Fetch")
-		self.url = "http://www.python.org/"
-		self.tmpname = "Fetch_Tmp_%d.html" % os.getpid()
-		self.officialname = "Python.html"
+Example
+-------
 
-	def execute(self):
-		self.logProgress("fetching data from %r" % self.url)
-		data = urllib.urlopen(self.url).read()
-		datasize = len(data)
-		self.logProgress("writing file %r (%d bytes)" %
-			(self.tmpname, datasize))
-		open(self.tmpname, "wb").write(data)
-		self.logProgress("renaming file %r to %r" %
-			(self.tmpname, self.officialname))
-		os.rename(self.tmpname, self.officialname)
-		self.logLoop("cached %r as %r (%d bytes)" %
-			(self.url, self.officialname, datasize))
+The following example illustrates the use of this module::
 
-if __name__=="__main__":
-	sisyphus.execute(Fetch())
-</prog>
-</example>
-</section>
+	#!/usr/bin/env python
+
+	import os
+	import urllib
+	from ll import sisyphus
+
+	class Fetch(sisyphus.Job):
+		"savely fetches an HTML file and saves it to a local file."
+
+		def __init__(self):
+			sisyphus.Job.__init__(self, 180, name="Fetch")
+			self.url = "http://www.python.org/"
+			self.tmpname = "Fetch_Tmp_%d.html" % os.getpid()
+			self.officialname = "Python.html"
+
+		def execute(self):
+			self.logProgress("fetching data from %r" % self.url)
+			data = urllib.urlopen(self.url).read()
+			datasize = len(data)
+			self.logProgress("writing file %r (%d bytes)" % (self.tmpname, datasize))
+			open(self.tmpname, "wb").write(data)
+			self.logProgress("renaming file %r to %r" % (self.tmpname, self.officialname))
+			os.rename(self.tmpname, self.officialname)
+			self.logLoop("cached %r as %r (%d bytes)" % (self.url, self.officialname, datasize))
+
+	if __name__=="__main__":
+		sisyphus.execute(Fetch())
 """
 
 
 from ll import url
 
 
-__docformat__ = "xist"
+__docformat__ = "reStructuredText"
 
 
 def _formattime(timestamp):
 	"""
-	format <arg>timestamp</arg> into a string.
+	Format :var:`timestamp` into a string.
 	"""
 	return timestamp.strftime("%d/%b/%Y %H:%M:%S")
 
 
 def _formattimedelta(timedelta):
 	"""
-	format <arg>timedelta</arg> into a string.
+	Format :var:`timedelta` into a string.
 	"""
 	rest = timedelta.seconds
 	(rest, secs) = divmod(rest, 60)
 	"""
 	def __init__(self, name, mode="a", buffering=True, encoding="iso-8859-1"):
 		"""
-		<p>create a new log file (which will be opened on the first write). Arguments are:</p>
-		<ul>
-		<li><arg>name</arg>: the filename (either as a string or a
-		<pyref module="ll.url" class="URL"><class>ll.url.URL</class></pyref> instance).</li>
-		<li><arg>mode</arg>: The mode for opening the file (should be <lit>"w"</lit> or <lit>"a"</lit>)</li>
-		<li><arg>buffering</arg>: the buffering for the file (<lit>0</lit> is unbuffered, <lit>1</lit> is line buffered, any other integer specifies the buffersize)</li>
-		<li><arg>encoding</arg>: the encoding to use for the strings written to the file</li>
-		</ul>
+		Create a new log file (which will be opened on the first write).
+		Arguments are:
+
+		:var:`name`
+			The filename (either as a string or a :class:`ll.url.URL` instance).
+
+		:var:`mode`
+			The mode for opening the file (should be ``"w"`` or ``"a"``).
+
+		:var:`buffering`
+			The buffering for the file (``0`` is unbuffered, ``1`` is line
+			buffered, any other integer specifies the buffersize).
+
+		:var:`encoding`
+			The encoding to use for the strings written to the file.
 		"""
 		self.starttime = datetime.datetime.now()
 		if not isinstance(name, url.URL):
 
 	def write(self, *texts):
 		"""
-		write <arg>texts</arg> to the log file.
+		Write :var:`texts` to the log file.
 		"""
 		now = datetime.datetime.now()
 		pid = os.getpid()
 
 class Job(object):
 	"""
-	<p>A Job object executes a task once.</p>
+	A Job object executes a task once.
 	
-	<p>The job announces its presence (and its process id) in a file that
-	is stored in the <dirname>~/run</dirname> directory. Logs will be created in
-	the <dirname>~/log</dirname> directory (This can be changes by deriving
-	new subclasses).</p>
+	The job announces its presence (and its process id) in a file that is stored
+	in the :dir:`~/run` directory. Logs will be created in the :dir:`~/log`
+	directory (This can be changes by deriving new subclasses).
 
-	<p>To use this class, derive your own class from it and overwrite
-	the <pyref method="execute">execute method</pyref>.</p>
+	To use this class, derive your own class from it and overwrite the
+	:meth:`execute` method.
 	"""
 
 	pidfilenametemplate = "~/run/%s.pid"
 
 	def __init__(self, maxruntime=0, name=None, raiseerrors=False, printkills=False):
 		"""
-		<p>create a new job. Arguments are:</p>
+		Create a new job. Arguments are:
 
-		<ul>
-		<li><arg>maxruntime</arg>: the maximum allowed runtime in seconds for this job;</li>
-		<li><arg>name</arg>: the name to be used for the log files. If <lit>None</lit>,
-		the name of the class will be used;</li>
-		<li><arg>raiseerrors</arg>: should exceptions that occur during the excution of the
-		job be raised (which results in a output to the terminal, or an email
-		from the cron daemon);</li>
-		<li><arg>printkills</arg>: should the fact that a previous job was killed,
-		be printed on stdout (resulting in a mail from the cron daemon)</li>
-		</ul>
+		:var:`maxruntime`: : integer
+			The maximum allowed runtime in seconds for this job;
+
+		:var:`name`: : string or :const:`None`
+			The name to be used for the log files. If :const:`None``, the name of
+			the class will be used;
+
+		:var:`raiseerrors`: : bool
+			should exceptions that occur during the excution of the job be raised
+			(which results in a output to the terminal, or an email from the cron
+			daemon);
+
+		:var:`printkills`: : bool
+			should the fact that a previous job was killed, be printed on stdout
+			(resulting in a mail from the cron daemon)
 		"""
 		self.starttime = datetime.datetime.now()
 		if not isinstance(maxruntime, datetime.timedelta):
 
 	def __writepid(self):
 		"""
-		creates the file containing the pid of the current process
+		Create the file containing the pid of the current process.
 		"""
 		if not self.pidfilewritten:
 			file = self.pidfilename.openwrite()
 
 	def __killpid(self):
 		"""
-		deletes the pid file
+		Delete the pid file.
 		"""
 		if self.pidfilewritten:
 			self.pidfilename.remove()
 
 	def logLoop(self, *texts):
 		"""
-		log the message texts to the loop and progress log.
-		(The call to <meth>logLoop</meth> should be the last statement
-		in the <pyref method="execute"><meth>execute</meth></pyref> method.)
+		Log the message texts to the loop and progress log. (The call to
+		:meth:`logLoop` should be the last statement in the :meth:`execute`
+		method.)
 		"""
 		self.loopLogfile.write(*texts)
 		self.progressLogfile.write(*texts)
 
 	def logProgress(self, *texts):
 		"""
-		log the message texts to the progress log
+		Log the message texts to the progress log.
 		"""
 		self.progressLogfile.write(*texts)
 
 	def logErrorOnly(self, *texts):
 		"""
-		log the error to the error log.
-		error may be a string or an exception object.
+		Log the error to the error log. :var:`texts` may be strings or exception
+		objects.
 		"""
 		self.errorLogfile.write(*texts)
 
 	def logError(self, error):
 		"""
-		log the error to the error log and the progress log.
-		error may be a string or an exception object.
+		Log the error to the error log and the progress log. :var:`texts` may be
+		strings or exception objects.
 		"""
 		self.progressLogfile.write(error)
 		self.errorLogfile.write(error)
 
 	def execute(self):
 		"""
-		Execute the job once.
-		At the end of the job you should write one line to the loop log.
-		Overwrite in subclasses.
+		Execute the job once. At the end of the job you should write one line to
+		the loop log. Overwrite in subclasses.
 		"""
 		self.logLoop("done")
 
 	def failed(self):
 		"""
-		Called when running the job generated an exception.
-		Overwrite in subclasses, to e.g. rollback your database transactions.
+		Called when running the job generated an exception. Overwrite in
+		subclasses, to e.g. rollback your database transactions.
 		"""
 		pass
 
 	def handleexecution(self):
 		"""
-		handles executing the job including handling of duplicate or hanging jobs.
+		Handle executing the job including handling of duplicate or hanging jobs.
 		This is the method to be called from the outside world.
 		"""
 		try: # is there a pid file from a running job?
 				else:
 					msg = "Job still running (for %s; %s allowed; started on %s) with pid %d (according to %s)" % (_formattimedelta(self.starttime-lastmodified), _formattimedelta(self.maxruntime), _formattime(lastmodified), pid, self.pidfilename)
 					self.logErrorOnly(msg)
-					return # Return without calling execute()
+					return # Return without calling :meth:`execute`
 
 		try:
 			self.execute()
 
 def execute(*jobs):
 	"""
-	<p>Execute several jobs.</p>
+	Execute several jobs.
 
-	<p>Items in <arg>jobs</arg> are job objects, that will be executed sequentially.</p>
+	Items in :var:`jobs` are job objects, that will be executed sequentially.
 	"""
 	for job in jobs:
 		job.handleexecution()