Merge pull request #2 from jean/master

Merge documentation clean-up.

README.txt → README.rst

@@ -9,14 +9,14 @@ Plone 3 and 4.
 
 Installation
 ============
-You will typically run plone.app.async in a ZEO environment, where you
-will have one or more *worker* instances that act as dispatchers carrying out
-jobs queued by your main zope instances.
+You will typically run ``plone.app.async`` in a ZEO environment, where you
+will have one or more *worker* instances carrying out jobs queued by your
+main zope instances.
 
 For the sake of simplicity it is assumed that you have one instance that can
 queue new jobs, and one worker instance that consumes them, both operating on
 a single database. In this case your buildout configuration will look similar
-to::
+to the following::
 
   [zeo]
   recipe = plone.recipe.zope2zeoserver
@@ -43,7 +43,7 @@ to::
 There are two important stanzas here:
 
 * Each instance has to set the ``ZC_ASYNC_UUID`` environment variable in order
-  to integrate properly with zc.async.
+  to integrate properly with `zc.async`_.
 
 * Each instance loads the ``single_db_instance.zcml`` configuration.
   The worker instance loads the ``single_db_worker.zcml`` configuration

setup.py

@@ -6,7 +6,7 @@
 setup(name='plone.app.async',
       version=version,
       description="Integration package for zc.async allowing asynchronous operations in Plone",
-      long_description=open("README.txt").read() + "\n" +
+      long_description=open("README.rst").read() + "\n" +
           open(join("src", "plone", "app", "async", "README.txt")).read() + "\n" +
           open(join("docs", "HISTORY.txt")).read(),
       classifiers=[

src/plone/app/async/README.txt → src/plone/app/async/README.rst

@@ -5,15 +5,15 @@ Basic use
 ---------
 
 Assuming your setup is done correctly, you can start by obtaining the
-`AsyncService` utility:
+``AsyncService`` utility::
 
     >>> from zope.component import getUtility
     >>> from plone.app.async.interfaces import IAsyncService
     >>> async = getUtility(IAsyncService)
     >>> async
     <plone.app.async.service.AsyncService object at ...>
 
-You can already get the zc.async queues:
+You can already get the ``zc.async`` queues::
 
     >>> async.getQueues()
     <zc.async.queue.Queues object at ...>
@@ -26,12 +26,12 @@ You can already get the zc.async queues:
     <zc.async.queue.Queue object at ...>
 
 Let's define a simple function to be executed asynchronously. Note that the
-first argument **must** be a valid Zope object:
+first argument **must** be a valid Zope object::
 
     >>> def addNumbers(context, x1, x2):
     ...     return x1+x2
 
-and queue it:
+and queue it::
 
     >>> job = async.queueJob(addNumbers, self.folder, 40, 2)
     >>> len(queue)
@@ -40,9 +40,10 @@ and queue it:
     u'pending-status'
 
 
-In real life the job would be exectuted by the worker. In the tests we need to
-commit in order to let the  dispatcher become aware of the job and execute it.
-Also we wait for the job to complete before continuing with the test.
+In real life the job would be executed by the worker. In the tests we need
+to commit in order to let the  dispatcher become aware of the job and
+execute it.  Also we wait for the job to complete before continuing with the
+test::
 
     >>> import transaction
     >>> from zc.async.testing import wait_for_result
@@ -54,22 +55,22 @@ Batches of jobs
 ---------------
 
 Let's now try some jobs that create persistent objects. First define
-the tasks to be executed asynchronously:
+the tasks to be executed asynchronously::
 
     >>> def createDocument(context, id, title, description, body):
     ...     context.invokeFactory('Document', id,
     ...         title=title, description=description, text=body)
     ...     return context[id].id
 
-and
+and::
 
     >>> from Products.CMFCore.utils import getToolByName
     >>> def submitObject(context, id):
     ...     obj = context[id]
     ...     wt = getToolByName(context, 'portal_workflow')
     ...     wt.doActionFor(obj, 'submit')
 
-Queue a job that creates a document and another that submits it:
+Queue a job that creates a document and another that submits it::
 
     >>> job = async.queueJob(createDocument, self.folder,
     ...     'foo', 'title', 'description', 'body')
@@ -80,7 +81,7 @@ Because by default the jobs are executed with the default quota set to 1,
 (i.e. only one job can be executed at a time), jobs are executed serially and
 according to the order by which they were submitted. Hence, waiting for the
 job that submits the document implies that the one that created it has already 
-been carried out.
+been carried out::
 
     >>> wait_for_result(job2)
     >>> wt = getToolByName(self.folder, 'portal_workflow')
@@ -89,7 +90,7 @@ been carried out.
     'pending'
 
 You can also queue a *batch* of jobs to be executed serially as one job by use
-of queueSerialJobs:
+of ``queueSerialJobs``::
 
     >>> from plone.app.async.service import makeJob
     >>> job = async.queueSerialJobs(
@@ -112,13 +113,13 @@ Security and user permissions
 -----------------------------
 
 When a job is queued by some user, it is also executed by the same user, with
-the same roles and permissions. So for instance:
+the same roles and permissions. So for instance::
 
     >>> job = async.queueJob(createDocument, self.portal,
     ...     'foo', 'title', 'description', 'body')
     >>> transaction.commit()
 
-will fail as the user is not allowed to create content in the Plone root.
+will fail as the user is not allowed to create content in the Plone root::
 
     >>> wait_for_result(job)
     <zc.twist.Failure AccessControl.unauthorized.Unauthorized>
@@ -127,7 +128,7 @@ Handling failure and success
 ----------------------------
 
 If you need to act on the result of a job or handle a failure you can do
-so by adding callbacks. For instance,
+so by adding callbacks. For instance::
 
     >>> results = []
     >>> def job_success_callback(result):
@@ -139,7 +140,7 @@ so by adding callbacks. For instance,
     >>> results
     ['Success: 42']
 
-Failures can be handled in the same way. 
+Failures can be handled in the same way::
 
     >>> results = []
     >>> def failingJob(context):
@@ -154,7 +155,7 @@ Failures can be handled in the same way.
     [<zc.twist.Failure exceptions.RuntimeError>]
 
 It is also possible to handle all successful/failed jobs (for instance if you
-want to send an email upon failure) by subscribing to the respective event:
+want to send an email upon failure) by subscribing to the respective event::
 
     >>> def successHandler(event):
     ...     results.append(event.object)
@@ -173,7 +174,7 @@ want to send an email upon failure) by subscribing to the respective event:
     >>> results
     [42, 'exceptions.RuntimeError: FooBared']
 
-Let's clean up and unregister the success/failure handlers...
+Let's clean up and unregister the success/failure handlers...::
 
     >>> from zope.component import getGlobalSiteManager
     >>> gsm = getGlobalSiteManager()

src/plone/app/async/tests/test_doctests.py

@@ -33,7 +33,7 @@ def tearDown(test):
 
 def test_suite():
     suite = ZopeTestCase.FunctionalDocFileSuite(
-                'README.txt', package='plone.app.async',
+                'README.rst', package='plone.app.async',
                 test_class=FunctionalAsyncTestCase,
                 setUp=setUp, tearDown=tearDown,
                 optionflags=optionflags,