[Python-checkins] r62709 - in doctools/trunk: CHANGES doc/concepts.rst sphinx/directives/desc.py sphinx/latexwriter.py

[georg.brandl]

Author: georg.brandl
Date: Sun May  4 19:55:35 2008
New Revision: 62709

Log:
* Support for C class names (and const specifiers).
* Fix handling of describe environment.


Modified:
   doctools/trunk/CHANGES
   doctools/trunk/doc/concepts.rst
   doctools/trunk/sphinx/directives/desc.py
   doctools/trunk/sphinx/latexwriter.py

Modified: doctools/trunk/CHANGES
==============================================================================
--- doctools/trunk/CHANGES	(original)
+++ doctools/trunk/CHANGES	Sun May  4 19:55:35 2008
@@ -30,6 +30,9 @@
 * A new config value, `autoclass_content`, selects if the docstring of the
   class' ``__init__`` method is added to the directive's body.
 
+* Support for C++ class names (in the style ``Class::Function``) in C function
+  descriptions.
+
 Bugs fixed
 ----------
 

Modified: doctools/trunk/doc/concepts.rst
==============================================================================
--- doctools/trunk/doc/concepts.rst	(original)
+++ doctools/trunk/doc/concepts.rst	Sun May  4 19:55:35 2008
@@ -16,6 +16,16 @@
 slashes.  All values, parameters and suchlike referring to "documents" expect
 such a document name.
 
+.. cfunction:: Class::method(int bla, int foo) const
+
+   pass
+
+.. cmdoption:: --longopt <arg>
+
+.. class:: Test
+
+   .. method:: X
+
 
 The TOC tree
 ------------

Modified: doctools/trunk/sphinx/directives/desc.py
==============================================================================
--- doctools/trunk/sphinx/directives/desc.py	(original)
+++ doctools/trunk/sphinx/directives/desc.py	Sun May  4 19:55:35 2008
@@ -154,12 +154,14 @@
 c_sig_re = re.compile(
     r'''^([^(]*?)          # return type
         ([\w:]+)  \s*      # thing name (colon allowed for C++ class names)
-        (?: \((.*)\) )? $  # optionally arguments
+        (?: \((.*)\) )?    # optionally arguments
+        (\s+const)? $      # const specifier
     ''', re.VERBOSE)
 c_funcptr_sig_re = re.compile(
     r'''^([^(]+?)          # return type
         (\( [^()]+ \)) \s* # name in parentheses
-        \( (.*) \) $       # arguments
+        \( (.*) \)         # arguments
+        (\s+const)? $      # const specifier
     ''', re.VERBOSE)
 c_funcptr_name_re = re.compile(r'^\(\s*\*\s*(.*?)\s*\)$')
 
@@ -190,11 +192,18 @@
         m = c_sig_re.match(sig)
     if m is None:
         raise ValueError('no match')
-    rettype, name, arglist = m.groups()
+    rettype, name, arglist, const = m.groups()
 
     signode += addnodes.desc_type("", "")
     parse_c_type(signode[-1], rettype)
-    signode += addnodes.desc_name(name, name)
+    try:
+        classname, funcname = name.split('::', 1)
+        classname += '::'
+        signode += addnodes.desc_classname(classname, classname)
+        signode += addnodes.desc_name(funcname, funcname)
+        # name (the full name) is still both parts
+    except ValueError:
+        signode += addnodes.desc_name(name, name)
     # clean up parentheses from canonical name
     m = c_funcptr_name_re.match(name)
     if m:
@@ -222,6 +231,8 @@
             param += nodes.emphasis(' '+argname, ' '+argname)
         paramlist += param
     signode += paramlist
+    if const:
+        signode += addnodes.desc_classname(const, const)
     return name
 
 

Modified: doctools/trunk/sphinx/latexwriter.py
==============================================================================
--- doctools/trunk/sphinx/latexwriter.py	(original)
+++ doctools/trunk/sphinx/latexwriter.py	Sun May  4 19:55:35 2008
@@ -88,6 +88,7 @@
         self.ni = node['noindex']
         self.type = self.cls = self.name = self.params = ''
         self.count = 0
+        self.name = ''
 
 
 class LaTeXTranslator(nodes.NodeVisitor):
@@ -321,6 +322,9 @@
             else:
                 t2 = "{%s}" % d.name
         elif d.env == 'cfuncdesc':
+            if d.cls:
+                # C++ class names
+                d.name = '%s::%s' % (d.cls, d.name)
             t2 = "{%s}{%s}{%s}" % (d.type, d.name, d.params)
         elif d.env == 'cmemberdesc':
             try:
@@ -341,19 +345,35 @@
         self.body.append(t1 + t2)
 
     def visit_desc_type(self, node):
-        self.descstack[-1].type = self.encode(node.astext().strip())
+        d = self.descstack[-1]
+        if d.env == 'describe':
+            d.name += self.encode(node.astext())
+        else:
+            self.descstack[-1].type = self.encode(node.astext().strip())
         raise nodes.SkipNode
 
     def visit_desc_name(self, node):
-        self.descstack[-1].name = self.encode(node.astext().strip())
+        d = self.descstack[-1]
+        if d.env == 'describe':
+            d.name += self.encode(node.astext())
+        else:
+            self.descstack[-1].name = self.encode(node.astext().strip())
         raise nodes.SkipNode
 
     def visit_desc_classname(self, node):
-        self.descstack[-1].cls = self.encode(node.astext().strip())
+        d = self.descstack[-1]
+        if d.env == 'describe':
+            d.name += self.encode(node.astext())
+        else:
+            self.descstack[-1].cls = self.encode(node.astext().strip())
         raise nodes.SkipNode
 
     def visit_desc_parameterlist(self, node):
-        self.descstack[-1].params = self.encode(node.astext().strip())
+        d = self.descstack[-1]
+        if d.env == 'describe':
+            d.name += self.encode(node.astext())
+        else:
+            self.descstack[-1].params = self.encode(node.astext().strip())
         raise nodes.SkipNode
 
     def visit_refcount(self, node):
@@ -362,7 +382,9 @@
         self.body.append("}\\\\")
 
     def visit_desc_content(self, node):
-        pass
+        if node.children and isinstance(node.children[0], addnodes.desc):
+            # avoid empty desc environment which causes a formatting bug
+            self.body.append('~')
     def depart_desc_content(self, node):
         pass