Lerking/Phoenix
1
0
Fork 0
mirror of https://github.com/wxWidgets/Phoenix.git synced 2025-12-16 01:30:07 +01:00
Code Issues Actions Packages Projects Releases Wiki Activity

* Fix scanning extension modules for docstrings

Browse Source 
* Support documenting classes that are in a package's __init__ module
This commit is contained in:
Robin Dunn
2019-08-09 14:59:54 -07:00
committed by Robin Dunn
parent defa946fce
commit fa4683d8f7
3 changed files with 74 additions and 40 deletions
Download Patch File Download Diff File Expand all files Collapse all files

2
build.py
View File

@@ -1092,7 +1092,7 @@ def cmd_sphinx(options, args):
def cmd_wxlib(options, args): def cmd_wxlib(options, args):
from sphinxtools.modulehunter import ModuleHunter from sphinxtools.modulehunter import ModuleHunter
cmdTimer = CommandTimer('wx.lib') cmdTimer = CommandTimer('wxlib')
pwd = pushDir(phoenixDir()) pwd = pushDir(phoenixDir())
for wx_pkg in ['lib', 'py', 'svg', 'tools']: for wx_pkg in ['lib', 'py', 'svg', 'tools']:

71
sphinxtools/librarydescription.py
View File

@@ -43,23 +43,33 @@ def generic_summary(libraryItem, stream):
if libraryItem.kind in [object_types.LIBRARY, object_types.PACKAGE]: if libraryItem.kind in [object_types.LIBRARY, object_types.PACKAGE]:
list1 = libraryItem.GetItemByKind(object_types.PACKAGE) list1 = libraryItem.GetItemByKind(object_types.PACKAGE)
list2 = libraryItem.GetItemByKind(object_types.PY_MODULE, object_types.PYW_MODULE) list2 = libraryItem.GetItemByKind(object_types.PY_MODULE, object_types.PYW_MODULE)
list3 = libraryItem.GetItemByKind(object_types.FUNCTION)
list4 = libraryItem.GetItemByKind(object_types.KLASS, recurse=True)
templ = [templates.TEMPLATE_PACKAGE_SUMMARY, templates.TEMPLATE_MODULE_SUMMARY] all_lists = [list1, list2, list3, list4]
refs = ['mod', 'mod'] templ = [ templates.TEMPLATE_PACKAGE_SUMMARY,
templates.TEMPLATE_MODULE_SUMMARY,
templates.TEMPLATE_STD_FUNCTION_SUMMARY,
templates.TEMPLATE_STD_CLASS_SUMMARY
]
refs = ['mod', 'mod', 'func', 'ref']
add_tilde = [True, True, True, True]
elif libraryItem.kind in range(object_types.PY_MODULE, object_types.PYW_MODULE+1): elif libraryItem.kind in range(object_types.PY_MODULE, object_types.PYW_MODULE+1):
list1 = libraryItem.GetItemByKind(object_types.FUNCTION) list1 = libraryItem.GetItemByKind(object_types.FUNCTION)
list2 = libraryItem.GetItemByKind(object_types.KLASS, recurse=True) list2 = libraryItem.GetItemByKind(object_types.KLASS, recurse=True)
all_lists = [list1, list2]
templ = [templates.TEMPLATE_STD_FUNCTION_SUMMARY, templates.TEMPLATE_STD_CLASS_SUMMARY] templ = [templates.TEMPLATE_STD_FUNCTION_SUMMARY, templates.TEMPLATE_STD_CLASS_SUMMARY]
refs = ['func', 'ref'] refs = ['func', 'ref']
add_tilde = [True, True] add_tilde = [True, True]
elif libraryItem.kind == object_types.KLASS: elif libraryItem.kind == object_types.KLASS:
write_toc = False write_toc = False
list1 = libraryItem.GetItemByKind(object_types.METHOD, object_types.INSTANCE_METHOD) list1 = libraryItem.GetItemByKind(object_types.METHOD, object_types.BUILTIN_FUNCTION)
list2 = libraryItem.GetItemByKind(object_types.PROPERTY) list2 = libraryItem.GetItemByKind(object_types.PROPERTY)
all_lists = [list1, list2]
templ = [templates.TEMPLATE_METHOD_SUMMARY, templates.TEMPLATE_PROPERTY_SUMMARY] templ = [templates.TEMPLATE_METHOD_SUMMARY, templates.TEMPLATE_PROPERTY_SUMMARY]
refs = ['meth', 'attr'] refs = ['meth', 'attr']
add_tilde = [True, True] add_tilde = [True, True]
@@ -69,7 +79,7 @@ def generic_summary(libraryItem, stream):
toctree = '' toctree = ''
for index, sub_list in enumerate([list1, list2]): for index, sub_list in enumerate(all_lists):
table = [] table = []
for item in sub_list: for item in sub_list:
@@ -739,7 +749,7 @@ class Class(ParentBase):
stream.write(docs + '\n\n') stream.write(docs + '\n\n')
methods = self.GetItemByKind(object_types.METHOD, object_types.INSTANCE_METHOD) methods = self.GetItemByKind(object_types.METHOD, object_types.BUILTIN_FUNCTION)
properties = self.GetItemByKind(object_types.PROPERTY) properties = self.GetItemByKind(object_types.PROPERTY)
for meth in methods: for meth in methods:
@@ -776,8 +786,8 @@ class Class(ParentBase):
self.signature = self.signature.strip() self.signature = self.signature.strip()
if len(self.signature) < 2: # if len(self.signature) < 2: # ???
self.is_redundant = True # self.is_redundant = True
if self.GetShortName().startswith('__test') or '.extern.' in self.name: if self.GetShortName().startswith('__test') or '.extern.' in self.name:
self.is_redundant = True self.is_redundant = True
@@ -785,7 +795,7 @@ class Class(ParentBase):
if self.is_redundant: if self.is_redundant:
return return
methods = self.GetItemByKind(object_types.METHOD, object_types.INSTANCE_METHOD) methods = self.GetItemByKind(object_types.METHOD, object_types.BUILTIN_FUNCTION)
method_list = [] method_list = []
for meth in methods: for meth in methods:
@@ -901,7 +911,18 @@ class Method(ChildrenBase):
self.signature = self.signature.replace('*', r'\*') self.signature = self.signature.replace('*', r'\*')
if not self.signature.strip(): if not self.signature.strip():
self.is_redundant = True # if there is no signature, then check if the first line of
# docstring looks like it might be it
lines = self.docs.split('\n')
first = lines[0]
rest = '\n'.join(lines[1:]) if len(lines) > 1 else ''
sig_start = self.GetShortName() + '('
if sig_start in first:
self.signature = first[first.find(sig_start):]
self.docs = rest.strip()
# if not self.signature.strip(): # ???
# self.is_redundant = True
def Write(self, stream): def Write(self, stream):
@@ -944,21 +965,23 @@ class Property(ChildrenBase):
self.getter = self.setter = self.deleter = '' self.getter = self.setter = self.deleter = ''
try: # is it a real property?
if item.fget: if isinstance(item, property):
self.getter = item.fget.__name__ try:
if item.fset: if item.fget:
self.setter = item.fset.__name__ self.getter = item.fget.__name__
if item.fdel: if item.fset:
self.deleter = item.fdel.__name__ self.setter = item.fset.__name__
except AttributeError: if item.fdel:
# Thank you for screwing it up, Cython... self.deleter = item.fdel.__name__
if item.fget: except AttributeError:
self.getter = item.fget.__class__.__name__ # Thank you for screwing it up, Cython...
if item.fset: if item.fget:
self.setter = item.fset.__class__.__name__ self.getter = item.fget.__class__.__name__
if item.fdel: if item.fset:
self.deleter = item.fdel.__class__.__name__ self.setter = item.fset.__class__.__name__
if item.fdel:
self.deleter = item.fdel.__class__.__name__
self.docs = getdoc(item) self.docs = getdoc(item)
self.comments = getcomments(item) self.comments = getcomments(item)

41
sphinxtools/modulehunter.py
View File

@@ -7,7 +7,6 @@
import os import os
import sys import sys
import types import types
import importlib
import traceback import traceback
import pkgutil import pkgutil
@@ -219,12 +218,14 @@ def inspect_source(method_class, obj, source):
def is_classmethod(instancemethod): def is_classmethod(instancemethod):
""" Determine if an instancemethod is a classmethod. """ """ Determine if an instancemethod is a classmethod. """
attribute = (isPython3() and ['__self__'] or ['im_self'])[0] # attribute = (isPython3() and ['__self__'] or ['im_self'])[0]
# if hasattr(instancemethod, attribute):
# return getattr(instancemethod, attribute) is not None
# return False
if hasattr(instancemethod, attribute): return isinstance(
return getattr(instancemethod, attribute) is not None instancemethod,
(classmethod, types.MethodType, types.ClassMethodDescriptorType))
return False
def describe_func(obj, parent_class, module_name): def describe_func(obj, parent_class, module_name):
@@ -279,7 +280,10 @@ def describe_func(obj, parent_class, module_name):
klass.number_lines = '%d' % len(source_code.split('\n')) klass.number_lines = '%d' % len(source_code.split('\n'))
if isinstance(obj, staticmethod): if isinstance(obj, staticmethod):
klass.method = method = object_types.STATIC_METHOD klass.kind = method = object_types.STATIC_METHOD
if is_classmethod(obj):
klass.kind = method = object_types.CLASS_METHOD
try: try:
code = None code = None
@@ -338,7 +342,8 @@ def describe_class(obj, module_class, module_name, constants):
continue continue
try: try:
item = getattr(obj, name) # item = getattr(obj, name) # ????
item = obj_dict.get(name)
except AttributeError: except AttributeError:
# Thanks to ReportLab for this funny exception... # Thanks to ReportLab for this funny exception...
continue continue
@@ -351,13 +356,10 @@ def describe_class(obj, module_class, module_name, constants):
if ismodule(item): if ismodule(item):
continue continue
if ismemberdescriptor(item) or isgetsetdescriptor(item):
continue
if isbuiltin(item): if isbuiltin(item):
count += 1 count += 1
elif ismethod(item) or isfunction(item) or ismethoddescriptor(item) or \ elif ismethod(item) or isfunction(item) or ismethoddescriptor(item) or \
isinstance(item, types.MethodType): isinstance(item, (classmethod, types.MethodType, types.ClassMethodDescriptorType)):
count += 1 count += 1
describe_func(item, klass, module_name) describe_func(item, klass, module_name)
elif isclass(item): elif isclass(item):
@@ -365,7 +367,7 @@ def describe_class(obj, module_class, module_name, constants):
describe_class(item, klass, module_name, constants) describe_class(item, klass, module_name, constants)
else: else:
name = class_name + '.' + name name = class_name + '.' + name
if isinstance(item, property): if isinstance(item, property) or isgetsetdescriptor(item):
item_class = Property(name, item) item_class = Property(name, item)
klass.Add(item_class) klass.Add(item_class)
@@ -406,6 +408,12 @@ def describe_class(obj, module_class, module_name, constants):
klass.signature = description.strip() klass.signature = description.strip()
klass.number_lines = '%d' % len(source_code.split('\n')) klass.number_lines = '%d' % len(source_code.split('\n'))
if not klass.signature:
if klass.superClasses:
klass.signature = '{}({})'.format(obj.__name__, ','.join(klass.superClasses))
else:
klass.signature = '{}(object)'.format(obj.__name__)
def describe_module(module, kind, constants=[]): def describe_module(module, kind, constants=[]):
""" """
@@ -478,7 +486,9 @@ def Import(init_name, import_name, full_process=True):
sys.path.insert(0, dirname) sys.path.insert(0, dirname)
try: try:
mainmod = importlib.import_module(import_name) #mainmod = importlib.import_module(import_name)
terminal_module = import_name.split('.')[-1]
mainmod = __import__(import_name, globals(), fromlist=[terminal_module])
except (ImportError, NameError): except (ImportError, NameError):
message = format_traceback() message = format_traceback()
print('Error: %s' % message) print('Error: %s' % message)
@@ -527,7 +537,8 @@ def FindModuleType(filename):
def SubImport(import_string, module, parent_class, ispkg): def SubImport(import_string, module, parent_class, ispkg):
try: try:
submod = importlib.import_module(import_string) #submod = importlib.import_module(import_string)
submod = __import__(import_string, globals(), fromlist=[module])
except: except:
# pubsub and Editra can be funny sometimes... # pubsub and Editra can be funny sometimes...
message = "Unable to import module/package '%s.%s'.\n Exception was: %s"%(import_string, module, format_traceback()) message = "Unable to import module/package '%s.%s'.\n Exception was: %s"%(import_string, module, format_traceback())