Phoenix:

- Correctly handle and reference inherited methods inside class/method descriptions;
- Reformat the method's short descriptions in the Summary tables to properly show hyperlinks to the methods themselves.

git-svn-id: https://svn.wxwidgets.org/svn/wx/wxPython/Phoenix/trunk@71720 c3d73ce0-8a6f-49c7-b76d-6d57e0e08775

etgtools/sphinx_generator.py

@@ -2275,11 +2275,11 @@ class XMLDocString(object):
             stream.write(snippets)
 
         if klass.method_list:
-            summary = MakeSummary(klass.method_list, templates.TEMPLATE_METHOD_SUMMARY, 'meth')
+            summary = MakeSummary(name, klass.method_list, templates.TEMPLATE_METHOD_SUMMARY, 'meth')
             stream.write(summary)
 
         if klass.property_list:
-            summary = MakeSummary(klass.property_list, templates.TEMPLATE_PROPERTY_SUMMARY, 'attr')
+            summary = MakeSummary(name, klass.property_list, templates.TEMPLATE_PROPERTY_SUMMARY, 'attr')
             stream.write(summary)
 
         stream.write(templates.TEMPLATE_API)

sphinxtools/librarydescription.py

@@ -87,7 +87,7 @@ def generic_summary(libraryItem, stream):
                 toctree += '   %s\n'%item.name
 
         if table:
-            summary = MakeSummary(table, templ[index], refs[index], add_tilde[index])
+            summary = MakeSummary(libraryItem.name, table, templ[index], refs[index], add_tilde[index])
             stream.write(summary)
             
     if toctree and write_toc:

sphinxtools/postprocess.py

@@ -261,6 +261,7 @@ def FindInherited(input, class_summary, enum_base, text):
             continue
         
         methods, bases, short_description = class_summary[curr_class]
+        methods = [m.split('.')[-1] for m in methods]
 
         if meth_name in methods:
             continue
@@ -268,20 +269,22 @@ def FindInherited(input, class_summary, enum_base, text):
         newstr = ''
 
         for cls in bases:
+
             if cls not in class_summary:
                 continue
 
             submethods, subbases, subshort = class_summary[cls]
-
-            if meth_name in submethods:
+            short_submethods = [m.split('.')[-1] for m in submethods]
+            
+            if meth_name in short_submethods:
                 if not hasdot:
                     newstr = ':meth:`~%s.%s`'%(cls, meth_name)                        
                 elif not hastilde:
-                    newstr = ':meth:`%s.%s`'%(cls, meth_name)
+                    newstr = ':meth:`%s.%s <%s.%s>`'%(curr_class, meth_name, cls, meth_name)
                 elif hasdot:
                     newstr = ':meth:`~%s.%s`'%(cls, meth_name)
                 else:
-                    newstr = ':meth:`%s.%s`'%(cls, meth_name)
+                    newstr = ':meth:`%s.%s <%s.%s>`'%(curr_class, meth_name, cls, meth_name)
 
                 break                        
 

sphinxtools/utilities.py

@@ -17,6 +17,7 @@ import codecs
 import shutil
 import glob
 import imp
+import re
 
 if sys.version_info < (3,):
     import cPickle as pickle
@@ -475,14 +476,15 @@ def FindControlImages(elementOrString):
 
 # ----------------------------------------------------------------------- #
 
-def MakeSummary(item_list, template, kind, add_tilde=True):
+def MakeSummary(class_name, item_list, template, kind, add_tilde=True):
     """
     This function generates a table containing a method/property name
     and a shortened version of its docstrings.
 
-    :param list `item_list`: a list of tuples like `(method/property name, short docstrings)`.
+    :param string `class_name`: the class name containing the method/property lists;
+    :param list `item_list`: a list of tuples like `(method/property name, short docstrings)`;
     :param string `template`: the template to use (from `sphinxtools/templates.py`, can
-     be the ``TEMPLATE_METHOD_SUMMARY`` or the ``TEMPLATE_PROPERTY_SUMMARY``.
+     be the ``TEMPLATE_METHOD_SUMMARY`` or the ``TEMPLATE_PROPERTY_SUMMARY``;
     :param string `kind`: can be ``:meth:`` or ``:attr:`` or ``:ref:`` or ``:mod:``;
     :param bool `add_tilde`: ``True`` to add the ``~`` character in front of the first
      summary table column, ``False`` otherwise.
@@ -505,8 +507,20 @@ def MakeSummary(item_list, template, kind, add_tilde=True):
             substr = ':%s:`~%s`'%(kind, method)
         else:
             substr = ':%s:`%s`'%(kind, method)
-            
-        summary += format%(substr, simple_docs) + '\n'
+
+        new_docs = simple_docs
+
+        if kind == 'meth':
+            regex = re.findall(r':meth:\S+', simple_docs)
+            for regs in regex:
+                if '.' in regs:
+                    continue
+
+                meth_name = regs[regs.index('`')+1:regs.rindex('`')]
+                newstr = ':meth:`~%s.%s`'%(class_name, meth_name)
+                new_docs = new_docs.replace(regs, newstr, 1)
+                            
+        summary += format%(substr, new_docs) + '\n'
 
     summary += '='*maxlen + ' ' + '='*80 + "\n"