1. jdb
  2. sphinx

Commits

Georg Brandl  committed 97dbc3c

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

  • Participants
  • Parent commits 41891ce
  • Branches default

Comments (0)

Files changed (3)

File doc/domains.rst

View file
           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
-      
-      .. rst:directive:: .. bar:: baz
-     
-   will be rendered as:
-     
-      .. 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

File sphinx/domains/rst.py

View file
 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.
     """
-    
+
     def add_target_and_index(self, name, sig, signode):
         if name not in self.state.document.ids:
             signode['names'].append(name)
             signode['ids'].append(name)
             signode['first'] = (not self.names)
             self.state.document.note_explicit_target(signode)
-        
+
             objects = self.env.domaindata['rst']['objects']
             if name in objects:
                 self.env.warn(
         if indextext:
             self.indexnode['entries'].append(('single', indextext,
                                               name, name))
-    
+
     def get_index_text(self, objectname, name):
         if self.objtype == 'directive':
             return _('%s (directive)') % name
             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()
     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'
     label = 'reStructuredText'
-    
+
     object_types = {
         'directive': ObjType(l_('reStructuredText directive'), 'dir'),
         'role':      ObjType(l_('reStructuredText role'),      'role'),
     initial_data = {
         'objects': {},  # fullname -> docname, objtype
     }
-    
+
     def clear_doc(self, docname):
         for name, (doc, _) in self.data['objects'].items():
             if doc == docname:
                 del self.data['objects'][name]
-    
+
     def resolve_xref(self, env, fromdocname, builder, typ, target, node,
                      contnode):
         objects = self.data['objects']
-        
+
         if not target in objects:
             return None
         return make_refnode(builder, fromdocname, objects[target][0], target,
                contnode, target)
-    
+
     def get_objects(self):
         for name, (docname, type) in self.data['objects'].iteritems():
             yield name, type, docname, name, 1
-
-

File tests/test_rst_domain.py

View file
 from sphinx.domains.rst import parse_directive
 
 def test_parse_directive():
-        
+
     s = parse_directive(' foö  ')
     assert s == ('foö', '')
-    
+
     s = parse_directive(' ..    foö ::  ')
     assert s == ('foö', '')
-    
+
     s = parse_directive('.. foö:: args1 args2')
     assert s == ('foö', 'args1 args2')
-    
+
     s = parse_directive('.. :: bar')
     assert s == ('.. :: bar', '')