Cleanup trailing whitespace and fix a few nits with the rst domain.

doc/domains.rst

@@ -599,38 +599,50 @@ These roles are provided to refer to the described objects:
           js:data
           js:attr
 
+
 The reStructuredText domain
 ---------------------------
 
-The reStructuredText domain (**rst**) provides the following directives:
+The reStructuredText domain (name **rst**) provides the following directives:
 
 .. directive:: .. rst:directive:: name
 
-   Describes a reST directive. The directive syntax (`..` prefix and 
-   `::` suffix) is optional and will be automatically added if not 
-   present. For example::
+   Describes a reST directive.  The *name* can be a single directive name or
+   actual directive syntax (`..` prefix and `::` suffix) with arguments that
+   will be rendered differently.  For example::
 
       .. rst:directive:: foo
 
+         Foo description.
+
       .. rst:directive:: .. bar:: baz
 
+         Bar description.
+
    will be rendered as:
 
       .. rst:directive:: foo
 
+         Foo description.
+
       .. rst:directive:: .. bar:: baz
 
+         Bar description.
+
 .. directive:: .. rst:role:: name
 
    Describes a reST role.  For example::
 
       .. rst:role:: foo
 
+         Foo description.
 
    will be rendered as:
 
       .. rst:role:: foo
 
+         Foo description.
+
 These roles are provided to refer to the described objects:
 
 .. rst:role:: rst:dir

sphinx/domains/rst.py

@@ -18,8 +18,10 @@ from sphinx.directives import ObjectDescription
 from sphinx.roles import XRefRole
 from sphinx.util.nodes import make_refnode
 
+
 dir_sig_re = re.compile(r'\.\. (.+?)::(.*)$')
 
+
 class ReSTMarkup(ObjectDescription):
     """
     Description of generic reST markup.
@@ -53,9 +55,10 @@ class ReSTMarkup(ObjectDescription):
             return _('%s (role)') % name
         return ''
 
+
 def parse_directive(d):
     """
-    Parses a directive. Returns (directive, arguments) string tuple. 
+    Parses a directive signature. Returns (directive, arguments) string tuple.
     if no arguments are given, returns (directive, '').
     """
     dir = d.strip()
@@ -66,28 +69,31 @@ def parse_directive(d):
     if not m:
         return (dir, '')
     parsed_dir, parsed_args = m.groups()
-    return (parsed_dir.strip(), parsed_args.strip())
+    return (parsed_dir.strip(), ' ' + parsed_args.strip())
+
 
 class ReSTDirective(ReSTMarkup):
     """
-    Description of reST directive.
+    Description of a reST directive.
     """
     def handle_signature(self, sig, signode):
         name, args = parse_directive(sig)
-        dec_name = '.. %s::' % name
-        signode += addnodes.desc_name(dec_name, dec_name)
+        desc_name = '.. %s::' % name
+        signode += addnodes.desc_name(desc_name, desc_name)
         if len(args) > 0:
             signode += addnodes.desc_addname(args, args)
         return name
 
+
 class ReSTRole(ReSTMarkup):
     """
-    Description of reST role.
+    Description of a reST role.
     """
     def handle_signature(self, sig, signode):
         signode += addnodes.desc_name(':%s:' % sig, ':%s:' % sig)
         return sig
 
+
 class ReSTDomain(Domain):
     """ReStructuredText domain."""
     name = 'rst'
@@ -126,5 +132,3 @@ class ReSTDomain(Domain):
     def get_objects(self):
         for name, (docname, type) in self.data['objects'].iteritems():
             yield name, type, docname, name, 1
-
-