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::
-   
+
+   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