various doc improvements

radix · radix · commit f1e522c94a09 · 2014-12-29T16:54:58.000-06:00
diff --git a/docs/source/conf.py b/docs/source/conf.py
@@ -33,6 +33,9 @@
     'sphinx.ext.viewcode',
 ]
 
+# RADIX CUSTOMIZATION
+autoclass_content = 'both'
+
 # Add any paths that contain templates here, relative to this directory.
 templates_path = ['_templates']
 
diff --git a/effect/__init__.py b/effect/__init__.py
@@ -7,36 +7,37 @@
 
 Here's a quick tour of the Effect library:
 
-- Intent: An object which specifies some action to perform, ideally with simple
-  inert data in public attributes. For example, ReadLine(prompt='> ')
+- Intent: An object which describes a desired action, ideally with simple
+  inert data in public attributes. For example, ``ReadLine(prompt='> ')`` could
+  be an intent that describes the desire to read a line from the user after
+  showing a prompt.
 - :obj:`Effect`: An object which binds callbacks to receive the result of
   performing an intent.
 - Performer: A callable that takes the Dispatcher, an Intent, and a Box. It
   executes the Intent and puts the result in the Box. For example, the
-  performer for ReadLine() would read a line from STDIN.
+  performer for ``ReadLine()`` could call ``raw_input(intent.prompt)``.
 - Dispatcher: A callable that takes an Intent and finds the Performer that can
   execute it (or None). See :obj:`TypeDispatcher` and :obj:`ComposedDispatcher`
   for handy pre-built dispatchers.
-- Box: An object that has 'succeed' and 'fail' methods for providing the result
-  of an execution (potentially asynchronously). Usually you don't need to care
-  about this, if you define your performers with :func:`effect.sync_performer`
-  or :func:`effect.twisted.deferred_performer`.
+- Box: An object that has ``succeed`` and ``fail`` methods for providing the
+  result of an execution (potentially asynchronously). Usually you don't need
+  to care about this, if you define your performers with
+  :func:`effect.sync_performer` or :func:`effect.twisted.deferred_performer`.
 
 There's a few main things you need to do to use Effect.
 
 - Define some intents to describe your side-effects (or use a library
   containing intents that already exist). For example, an ``HTTPRequest``
-  intent that has 'method', 'url', etc attributes.
+  intent that has ``method``, ``url``, etc attributes.
 - Write your application code to create effects like
   ``Effect(HTTPRequest(...))`` and attach callbacks to them with
   :func:`Effect.on`.
 - As close as possible to the top-level of your application, perform your
   effect(s) with :func:`perform`.
 - You will need to pass a dispatcher to :func:`perform`. You should create one
-  by using :class:`effect.dispatcher.ComposedDispatcher` to compose
-  :obj:`effect.base_dispatcher` (which performers for built-in effects) and a
-  :class:`effect.dispatcher.TypeDispatcher` with your own performers (e.g. for
-  ``HTTPRequest``).
+  by creating a :class:`TypeDispatcher` with your own performers (e.g. for
+  ``HTTPRequest``), and composing it with :obj:`effect.base_dispatcher` (which
+  has performers for built-in effects) using :class:`ComposedDispatcher`.
 """
 
 from __future__ import absolute_import
@@ -49,6 +50,7 @@
     base_dispatcher)
 from ._dispatcher import ComposedDispatcher, TypeDispatcher
 
+
 __all__ = [
     "Effect", "perform", "NoPerformerFoundError",
     "NotSynchronousError", "sync_perform", "sync_performer",
diff --git a/effect/_base.py b/effect/_base.py
@@ -19,15 +19,10 @@ class Effect(object):
     allow binding callbacks to be called with the result of the effect.
 
     Effects can be performed with :func:`perform`.
-
-    (You're an object-oriented programmer.
-     You probably want to subclass this.
-     Don't.)
     """
     def __init__(self, intent, callbacks=None):
         """
-        :param intent: An object that describes an effect to be
-            performed.
+        :param intent: An object that describes an effect to be performed.
         """
         self.intent = intent
         if callbacks is None:
diff --git a/effect/_dispatcher.py b/effect/_dispatcher.py
@@ -13,8 +13,7 @@ class TypeDispatcher(object):
     """
     def __init__(self, mapping):
         """
-        :param collections.Mapping mapping: A mapping of intent type to
-        performer.
+        :param collections.Mapping mapping: mapping of intent type to performer
         """
         self.mapping = mapping
 

Original file line number	Diff line number	Diff line change
`@@ -33,6 +33,9 @@`
`33`	`33`	`'sphinx.ext.viewcode',`
`34`	`34`	`]`
`35`	`35`
	`36`	`+# RADIX CUSTOMIZATION`
	`37`	`+autoclass_content = 'both'`
	`38`	`+`
`36`	`39`	`# Add any paths that contain templates here, relative to this directory.`
`37`	`40`	`templates_path = ['_templates']`
`38`	`41`