Tweak docstrings under nose2/

I mostly added markup, as follows:

- I tried to use `:role:` directives wherever I could
- If I wasn’t sure which role to use, I used double backticks

Besides that, I made a few (very) limited edits to text.  These are all minor, and chiefly motivated by phrasing and clarity.

nose2/compat.py

@@ -1,7 +1,7 @@
 """unittest/unittest2 compatibility wrapper.
 
-Anything internal to nose2 *must* import unittest from here, to be
-sure that it is using unittest2 when on older pythons.
+Anything internal to nose2 *must* import unittest from here to be
+certain that it is using unittest2 when run on older Python versions.
 
 Yes::
 
@@ -26,7 +26,7 @@
     unittest.installHandler
 except AttributeError:
     raise ImportError(
-        "Built-in unittest version too old, unittest2 is required")
+        "Built-in unittest version too old; unittest2 is required")
 
 __unittest = True
 

nose2/config.py

@@ -24,8 +24,8 @@ def __getitem__(self, key):
     def as_bool(self, key, default=None):
         """Get key value as boolean
 
-        1, t, true, on, yes and y (case insensitive) are accepted as True
-        values. All other values are False.
+        1, t, true, on, yes and y (case insensitive) are accepted as ``True``
+        values. All other values are ``False``.
 
         """
         try:

nose2/events.py

@@ -69,7 +69,7 @@ class Plugin(six.with_metaclass(PluginMeta)):
     .. attribute :: commandLineSwitch
 
        A tuple of (short opt, long opt, help text) that defines a command
-       line flag that activates this plugin. The short opt may be None. If
+       line flag that activates this plugin. The short opt may be ``None``. If
        defined, it must be a single upper-case character. Both short and
        long opt must *not* start with dashes.
 
@@ -84,7 +84,7 @@ class Plugin(six.with_metaclass(PluginMeta)):
     .. attribute :: alwaysOn
 
        If this plugin should automatically register itself, set alwaysOn to
-       True. Default is False.
+       ``True``. Default is ``False``.
 
     .. note ::
 
@@ -312,7 +312,7 @@ class Event(object):
 
     .. attribute :: handled
 
-       Set to True to indicate that a plugin has handled the event,
+       Set to ``True`` to indicate that a plugin has handled the event,
        and no other plugins or core systems should process it further.
 
     .. attribute :: version
@@ -442,7 +442,7 @@ def execute(suite, result):
              ...
 
     To prevent normal test execution, plugins may set ``handled`` on
-    this event to True. When ``handled`` is true, the test executor
+    this event to ``True``. When ``handled`` is true, the test executor
     does not run at all.
 
     """
@@ -562,19 +562,19 @@ class TestOutcomeEvent(Event):
 
        If the test resulted in an exception, the tuple of (exception
        class, exception value, traceback) as returned by
-       sys.exc_info(). If the test did not result in an exception,
-       None.
+       ``sys.exc_info()``. If the test did not result in an exception,
+       ``None``.
 
     .. attribute :: reason
 
-       For test outcomes that include a reason (Skips, for example),
+       For test outcomes that include a reason (``Skips``, for example),
        the reason.
 
     .. attribute :: expected
 
        Boolean indicating whether the test outcome was expected. In
        general, all tests are expected to pass, and any other outcome
-       will have expected as False. The exceptions to that rule are
+       will have expected as ``False``. The exceptions to that rule are
        unexpected successes and expected failures.
 
     .. attribute :: shortLabel
@@ -629,7 +629,7 @@ class LoadFromModuleEvent(Event):
 
     Plugins may set ``handled`` on this event and return a test suite
     to prevent other plugins from loading tests from the module. If
-    any plugin sets ``handled`` to True, ``extraTests`` will be
+    any plugin sets ``handled`` to ``True``, ``extraTests`` will be
     ignored.
 
     """
@@ -672,7 +672,7 @@ class LoadFromTestCaseEvent(Event):
 
     Plugins may set ``handled`` on this event and return a test suite
     to prevent other plugins from loading tests from the test case. If
-    any plugin sets ``handled`` to True, ``extraTests`` will be
+    any plugin sets ``handled`` to ``True``, ``extraTests`` will be
     ignored.
 
     """
@@ -695,11 +695,11 @@ class LoadFromNamesEvent(Event):
 
     .. attribute :: names
 
-       List of test names. May be empty or None.
+       List of test names. May be empty or ``None``.
 
     .. attribute :: module
 
-       Module to load from. May be None. If not None, names should be
+       Module to load from. May be ``None``. If not ``None``, names should be
        considered relative to this module.
 
     .. attribute :: extraTests
@@ -710,7 +710,7 @@ class LoadFromNamesEvent(Event):
 
     Plugins may set ``handled`` on this event and return a test suite
     to prevent other plugins from loading tests from the test names. If
-    any plugin sets ``handled`` to True, ``extraTests`` will be
+    any plugin sets ``handled`` to ``True``, ``extraTests`` will be
     ignored.
 
     """
@@ -741,7 +741,7 @@ class LoadFromNameEvent(Event):
 
     .. attribute :: module
 
-       Module to load from. May be None. If not None, names should be
+       Module to load from. May be ``None``. If not ``None``, names should be
        considered relative to this module.
 
     .. attribute :: extraTests
@@ -752,7 +752,7 @@ class LoadFromNameEvent(Event):
 
     Plugins may set ``handled`` on this event and return a test suite
     to prevent other plugins from loading tests from the test name. If
-    any plugin sets ``handled`` to True, ``extraTests`` will be
+    any plugin sets ``handled`` to ``True``, ``extraTests`` will be
     ignored.
 
     """
@@ -804,7 +804,7 @@ class HandleFileEvent(Event):
 
     Plugins may set ``handled`` on this event and return a test suite
     to prevent other plugins from loading tests from the file. If
-    any plugin sets ``handled`` to True, ``extraTests`` will be
+    any plugin sets ``handled`` to ``True``, ``extraTests`` will be
     ignored.
 
     """
@@ -826,7 +826,7 @@ class MatchPathEvent(Event):
 
     """Event fired during file matching.
 
-    Plugins may return False and set ``handled`` on this event to prevent
+    Plugins may return ``False`` and set ``handled`` on this event to prevent
     a file from being matched as a test file, regardless of other system
     settings.
 
@@ -871,7 +871,7 @@ class GetTestCaseNamesEvent(Event):
     .. attribute :: testMethodPrefix
 
        Set this to change the test method prefix. Unless set by a plugin,
-       it is None.
+       it is ``None``.
 
     .. attribute :: extraNames
 
@@ -917,9 +917,9 @@ class ResultSuccessEvent(Event):
 
     .. attribute :: success
 
-       Set this to True to indicate that the test run was
+       Set this to ``True`` to indicate that the test run was
        successful. If no plugin sets the ``success`` to
-       True, the test run fails.
+       ``True``, the test run fails.
 
     """
     _attrs = Event._attrs + ('result', 'success')
@@ -943,7 +943,7 @@ class ResultStopEvent(Event):
 
     .. attribute :: shouldStop
 
-       Set to True to indicate that the test run should stop.
+       Set to ``True`` to indicate that the test run should stop.
 
     """
     _attrs = Event._attrs + ('result', 'shouldStop')
@@ -1069,7 +1069,7 @@ class UserInteractionEvent(Event):
     Plugins that capture stdout or otherwise prevent user interaction
     should respond to this event.
 
-    To prevent the user interaction from occurring, return False and
+    To prevent the user interaction from occurring, return ``False`` and
     set ``handled``. Otherwise, turn off whatever you are doing that
     prevents users from typing/clicking/touching/psionics/whatever.
 
@@ -1117,11 +1117,11 @@ class CreateTestsEvent(Event):
 
     .. attribute :: names
 
-       List of test names. May be empty or None.
+       List of test names. May be empty or ``None``.
 
     .. attribute :: module
 
-       Module to load from. May be None. If not None, names should be
+       Module to load from. May be ``None``. If not ``None``, names should be
        considered relative to this module.
 
     """

nose2/exceptions.py

@@ -7,4 +7,4 @@
 
 class TestNotFoundError(Exception):
 
-    """Exception raised when a named test cannot be found"""
+    """Raised when a named test cannot be found"""

nose2/loader.py

@@ -104,7 +104,7 @@ def sortTestMethodsUsing(self, name):
         return name.lower()
 
     def discover(self, start_dir=None, pattern=None):
-        """Compatibility shim for load_tests protocol."""
+        """Compatibility shim for ``load_tests`` protocol."""
         try:
             oldsd = self.session.startDir
             self.session.startDir = start_dir

nose2/main.py

@@ -18,9 +18,9 @@ class PluggableTestProgram(unittest.TestProgram):
     but most of them are ignored as their functions are
     handled by plugins.
 
-    :param module: Module in which to run tests. Default: __main__
-    :param defaultTest: Default test name. Default: None
-    :param argv: Command line args. Default: sys.argv
+    :param module: Module in which to run tests. Default: :func:`__main__`
+    :param defaultTest: Default test name. Default: ``None``
+    :param argv: Command line args. Default: ``sys.argv``
     :param testRunner: *IGNORED*
     :param testLoader: *IGNORED*
     :param exit: Exit after running tests?
@@ -49,7 +49,7 @@ class PluggableTestProgram(unittest.TestProgram):
 
           Overriding this attribute is the only way to customize
           the test loader class. Passing a test loader to
-          ``__init__`` does not work.
+          :class:`__init__` does not work.
 
     .. attribute :: runnerClass
 
@@ -60,7 +60,7 @@ class PluggableTestProgram(unittest.TestProgram):
 
           Overriding this attribute is the only way to customize
           the test runner class. Passing a test runner to
-          ``__init__`` does not work.
+          :func:`__init__` does not work.
 
     .. attribute :: defaultPlugins
 
@@ -103,7 +103,7 @@ def parseArgs(self, argv):
         """Parse command line args
 
         Parses arguments and creates a configuration session,
-        then calls createTests.
+        then calls :func:`createTests`.
 
         """
         self.session = self.sessionClass()
@@ -230,7 +230,7 @@ def loadPlugins(self):
         """Load available plugins
 
 
-        ``self.defaultPlugins`` and ``self.excludePlugins`` are passed
+        :func:`self.defaultPlugins`` and :func:`self.excludePlugins` are passed
         to the session to alter the list of plugins that will be
         loaded.
 
@@ -280,7 +280,7 @@ def _makeRunner(self):
 
     @classmethod
     def getCurrentSession(cls):
-        """Returns the current session or None if no `nose2.session.Session` is running.
+        """Returns the current session, or ``None`` if no :class:`nose2.session.Session` is running.
         
         """
         return cls._currentSession

nose2/plugins/attrib.py

@@ -20,7 +20,7 @@ def __init__(self):
         self.addArgument(
             self.eval_attribs, "E", "eval-attribute",
             "Select tests for whose attributes the "
-            "given Python expression evalures to True")
+            "given Python expression evaluates to ``True``")
 
     def handleArgs(self, args):
         """Register if any attribs defined"""

nose2/plugins/collect.py

@@ -17,15 +17,15 @@ class CollectOnly(Plugin):
 
     configSection = 'collect-only'
     commandLineSwitch = (None, 'collect-only',
-                         'Collect and output test names, do not run any tests')
+                         'Collect and output test names; do not run any tests')
     _mpmode = False
 
     def registerInSubprocess(self, event):
         event.pluginClasses.append(self.__class__)
         self._mpmode = True
 
     def startTestRun(self, event):
-        """Replace event.executeTests"""
+        """Replace ``event.executeTests``"""
         if self._mpmode:
             return
         event.executeTests = self.collectTests
@@ -34,7 +34,7 @@ def startSubprocess(self, event):
         event.executeTests = self.collectTests
 
     def collectTests(self, suite, result):
-        """Collect tests but don't run them"""
+        """Collect tests, but don't run them"""
         for test in suite:
             if isinstance(test, unittest.TestSuite):
                 self.collectTests(test, result)

nose2/plugins/debugger.py

@@ -6,7 +6,7 @@
 
 It fires :func:`beforeInteraction` before launching pdb and
 :func:`afterInteraction` after. Other plugins may implement
-:func:`beforeInteraction` to return False and set event.handled to
+:func:`beforeInteraction` to return ``False`` and set ``event.handled`` to
 prevent this plugin from launching pdb.
 
 """

nose2/plugins/dundertest.py

@@ -1,6 +1,6 @@
 """
 This plugin implements :func:`startTestRun`, which excludes all test objects
-that define a ``__test__`` attribute with a truth value of False.
+that define a ``__test__`` attribute that evaluates to ``False``.
 """
 from unittest import TestSuite
 from nose2 import events
@@ -10,15 +10,14 @@
 
 class DunderTestFilter(events.Plugin):
     """
-    Exclude all tests defining a ``__test__`` attribute with a truth value of
-    False.
+    Exclude all tests defining a ``__test__`` attribute that evaluates to ``False``.
     """
     alwaysOn = True
 
     def startTestRun(self, event):
         """
         Recurse :attr:`event.suite` and remove all test suites and test cases
-        that define a ``__test__`` attribute with a truth value of False.
+        that define a ``__test__`` attribute that evaluates to ``False``.
         """
         self.removeNonTests(event.suite)
 

nose2/plugins/junitxml.py

@@ -4,13 +4,15 @@
 This plugin implements :func:`startTest`, :func:`testOutcome` and
 :func:`stopTestRun` to compile and then output a test report in
 junit-xml format. By default, the report is written to a file called
-``nose2-junit.xml`` in the current working directory. You can
-configure the output filename by setting ``path`` in a ``[junit-xml]``
+``nose2-junit.xml`` in the current working directory. 
+
+You can configure the output filename by setting ``path`` in a ``[junit-xml]``
 section in a config file.  Unicode characters which are invalid in XML 1.0
-are replaced with the U+FFFD replacement character.  In the case that your
-software throws an error with an invalid byte string.  By default, the
-ranges of discouraged characters are replaced as well.  This can be
-changed by setting the keep_restricted configuration variable to True.
+are replaced with the ``U+FFFD`` replacement character.  In the case that your
+software throws an error with an invalid byte string.  
+
+By default, the ranges of discouraged characters are replaced as well.  This can be
+changed by setting the ``keep_restricted`` configuration variable to ``True``.
 
 """
 # Based on unittest2/plugins/junitxml.py,

nose2/plugins/loader/discovery.py

@@ -3,11 +3,11 @@
 
 This plugin implements nose2's automatic test module discovery. It
 looks for test modules in packages and directories whose names start
-with 'test', then fires the :func:`loadTestsFromModule` hook for each
+with ``test``, then fires the :func:`loadTestsFromModule` hook for each
 one to allow other plugins to load the actual tests.
 
 It also fires :func:`handleFile` for every file that it sees, and
-:func:`matchPath` for every python module, to allow other plugins to
+:func:`matchPath` for every Python module, to allow other plugins to
 load tests from other kinds of files and to influence which modules
 are examined for tests.