diff --git a/build.py b/build.py index 669b9a47..01492e7a 100755 --- a/build.py +++ b/build.py @@ -863,7 +863,7 @@ def cmd_etg(options, args): def cmd_sphinx(options, args): - from sphinxtools.postprocess import sphinxIndexes, makeHeadings, postProcess, genGallery + from sphinxtools.postprocess import genIndexes, makeHeadings, postProcess, genGallery cmdTimer = CommandTimer('sphinx') pwd = pushDir(phoenixDir()) @@ -885,7 +885,7 @@ def cmd_sphinx(options, args): txt = os.path.join(sphinxDir, os.path.splitext(rstName)[0] + '.txt') copyIfNewer(rst, txt) - sphinxIndexes(sphinxDir) + genIndexes(sphinxDir) genGallery() # Copy the hand-edited top level doc files too diff --git a/etg/_core.py b/etg/_core.py index 5f96182c..75c9a475 100644 --- a/etg/_core.py +++ b/etg/_core.py @@ -323,7 +323,7 @@ def run(): object. .. seealso:: - :func:`CallAfter` + :func:`wx.CallAfter` """, items = [ diff --git a/etg/bitmap.py b/etg/bitmap.py index e51c4542..551efaa6 100644 --- a/etg/bitmap.py +++ b/etg/bitmap.py @@ -198,7 +198,7 @@ def run(): 'premultiplied' by the alpha values. (The other platforms do the multiplication themselves.) - Unlike :func:`ImageFromBuffer` the bitmap created with this function + Unlike :func:`wx.ImageFromBuffer` the bitmap created with this function does not share the memory block with the buffer object. This is because the native pixel buffer format varies on different platforms, and so instead an efficient as possible copy of the @@ -245,7 +245,7 @@ def run(): as a string, bytearray, etc. The data object is expected to contain a series of RGB bytes and be at least width*height*3 bytes long. - Unlike :func:`ImageFromBuffer` the bitmap created with this function + Unlike :func:`wx.ImageFromBuffer` the bitmap created with this function does not share the memory block with the buffer object. This is because the native pixel buffer format varies on different platforms, and so instead an efficient as possible copy of the @@ -287,7 +287,7 @@ def run(): On Windows and Mac the RGB values will be 'premultiplied' by the alpha values. (The other platforms do the multiplication themselves.) - Unlike :func:`ImageFromBuffer` the bitmap created with this function + Unlike :func:`wx.ImageFromBuffer` the bitmap created with this function does not share the memory block with the buffer object. This is because the native pixel buffer format varies on different platforms, and so instead an efficient as possible copy of the diff --git a/etgtools/sphinx_generator.py b/etgtools/sphinx_generator.py index ce4d8535..28b6c0f3 100644 --- a/etgtools/sphinx_generator.py +++ b/etgtools/sphinx_generator.py @@ -46,7 +46,7 @@ from sphinxtools.utilities import convertToPython from sphinxtools.utilities import writeSphinxOutput from sphinxtools.utilities import findControlImages, makeSummary, pickleItem from sphinxtools.utilities import chopDescription, pythonizeType, wx2Sphinx -from sphinxtools.utilities import pickleClassInfo, isNumeric +from sphinxtools.utilities import pickleClassInfo, pickleFunctionInfo, isNumeric from sphinxtools.utilities import underscore2Capitals, countSpaces from sphinxtools.utilities import formatContributedSnippets from sphinxtools.utilities import PickleFile @@ -2639,13 +2639,15 @@ class XMLDocString(object): function = self.xml_item name = function.pyName or function.name + imm = ItemModuleMap() + fullname = imm.get_fullname(name) if self.is_overload: - definition = '**%s** '%name + definition = '**%s** ' % name else: - definition = '.. function:: ' + name + definition = '.. function:: ' + fullname - stream.write('\n%s'%definition) + stream.write('\n%s' % definition) stream.write(self.arguments.strip()) stream.write('\n\n') @@ -2956,7 +2958,7 @@ class SphinxGenerator(generators.DocsGeneratorBase): } if module.isARealModule: - filename = os.path.join(SPHINXROOT, self.current_module+'1classindex.pkl') + filename = os.path.join(SPHINXROOT, self.current_module+'1moduleindex.pkl') with PickleFile(filename) as pf: pf.items[DOCSTRING_KEY] = module.docstring @@ -2971,6 +2973,9 @@ class SphinxGenerator(generators.DocsGeneratorBase): # ----------------------------------------------------------------------- def generatePyFunction(self, function): + name = function.pyName if function.pyName else removeWxPrefix(function.name) + imm = ItemModuleMap() + fullname = imm.get_fullname(name) function.overloads = [] function.pyArgsString = function.argsString @@ -2981,21 +2986,30 @@ class SphinxGenerator(generators.DocsGeneratorBase): docstring = XMLDocString(function) docstring.kind = 'function' docstring.current_module = self.current_module - docstring.Dump() - + desc = chopDescription(docstring.docstrings) + pickleFunctionInfo(fullname, desc) + # ----------------------------------------------------------------------- def generateFunction(self, function): - + name = function.pyName if function.pyName else removeWxPrefix(function.name) + if name.startswith('operator'): + return + + imm = ItemModuleMap() + fullname = imm.get_fullname(name) + # docstring docstring = XMLDocString(function) docstring.kind = 'function' docstring.current_module = self.current_module - docstring.Dump() - + + desc = chopDescription(docstring.docstrings) + pickleFunctionInfo(fullname, desc) + def unIndent(self, item): diff --git a/sphinxtools/postprocess.py b/sphinxtools/postprocess.py index c84ad26e..5e0f3ac0 100644 --- a/sphinxtools/postprocess.py +++ b/sphinxtools/postprocess.py @@ -59,7 +59,7 @@ def makeHeadings(): # ----------------------------------------------------------------------- # -def sphinxIndexes(sphinxDir): +def genIndexes(sphinxDir): """ This is the main function called after the `etg` process has finished. @@ -73,8 +73,8 @@ def sphinxIndexes(sphinxDir): for file in pklfiles: if file.endswith('functions.pkl'): reformatFunctions(file) - elif 'classindex' in file: - makeClassIndex(sphinxDir, file) + elif 'moduleindex' in file: + makeModuleIndex(sphinxDir, file) buildEnumsAndMethods(sphinxDir) @@ -365,7 +365,7 @@ def reformatFunctions(file): if local_file.count('.') == 2: # Core functions - label = 'wx Core' + label = 'wx' else: label = '.'.join(local_file.split('.')[0:2]) @@ -386,6 +386,7 @@ def reformatFunctions(file): names = list(functions.keys()) names = sorted(names, key=str.lower) + imm = ItemModuleMap() for letter in letters: text += '.. _%s %s:\n\n%s\n^\n\n'%(label, letter, letter) @@ -393,7 +394,7 @@ def reformatFunctions(file): if fun[0].upper() != letter: continue - text += '* :func:`%s`\n'%fun + text += '* :func:`%s`\n' % imm.get_fullname(fun) text += '\n\n' @@ -406,14 +407,14 @@ def reformatFunctions(file): # ----------------------------------------------------------------------- # -def makeClassIndex(sphinxDir, file): +def makeModuleIndex(sphinxDir, file): text_file = os.path.splitext(file)[0] + '.txt' local_file = os.path.split(file)[1] if not newer(file, text_file): return - + pf = PickleFile(file) classes = pf.read() module_docstring = classes.get(DOCSTRING_KEY) @@ -422,7 +423,7 @@ def makeClassIndex(sphinxDir, file): if local_file.startswith('wx.1'): # Core functions - label = 'wx Core' + label = 'wx' module = 'wx' enumDots = 2 # Take care to get only files starting with "wx.UpperName", not @@ -469,12 +470,35 @@ def makeClassIndex(sphinxDir, file): contents.append(enum) contents.sort() - + + # Are there functions for this module too? + functionsFile = os.path.join(sphinxDir, module + '.functions.pkl') + if os.path.exists(functionsFile): + pf = PickleFile(functionsFile) + functions = list(pf.read().keys()) + functions.sort(key=lambda n: imm.get_fullname(n)) + + pf = PickleFile(os.path.join(SPHINXROOT, 'function_summary.pkl')) + function_summaries = pf.read() + + text += templates.TEMPLATE_MODULE_FUNCTION_SUMMARY + text += 80*'=' + ' ' + 80*'=' + '\n' + text += '%-80s **Short Description**\n' % '**Function**' + text += 80*'=' + ' ' + 80*'=' + '\n' + + for func_name in functions: + fullname = imm.get_fullname(func_name) + doc = function_summaries.get(fullname, '') + text += '%-80s %s\n' % (':func:`%s`' % fullname, doc) + + text += 80 * '=' + ' ' + 80 * '=' + '\n\n' + contents.append(module + '.functions') + toctree = '' for item in contents: - toctree += ' %s\n'%item + toctree += ' %s\n' % item - text += templates.TEMPLATE_TOCTREE%toctree + text += templates.TEMPLATE_TOCTREE % toctree writeIfChanged(text_file, text) diff --git a/sphinxtools/templates.py b/sphinxtools/templates.py index 5e99e084..efb857e3 100644 --- a/sphinxtools/templates.py +++ b/sphinxtools/templates.py @@ -178,6 +178,13 @@ Class Summary ''' +# Template for the functions header in the module index +TEMPLATE_MODULE_FUNCTION_SUMMARY = ''' +Functions Summary +================= + +''' + # Template for the class window styles, with the class name as input TEMPLATE_WINDOW_STYLES = ''' diff --git a/sphinxtools/utilities.py b/sphinxtools/utilities.py index 8bc3b5ff..15a9c1b7 100644 --- a/sphinxtools/utilities.py +++ b/sphinxtools/utilities.py @@ -637,7 +637,7 @@ def pickleItem(description, current_module, name, kind): if kind == 'function': pickle_file = os.path.join(SPHINXROOT, current_module + 'functions.pkl') else: - pickle_file = os.path.join(SPHINXROOT, current_module + '1classindex.pkl') + pickle_file = os.path.join(SPHINXROOT, current_module + '1moduleindex.pkl') with PickleFile(pickle_file) as pf: pf.items[name] = description @@ -667,6 +667,18 @@ def pickleClassInfo(class_name, element, short_description): pf.items[class_name] = (method_list, bases, short_description) +# ----------------------------------------------------------------------- # + +def pickleFunctionInfo(fullname, short_description): + """ + Saves the short description for each function, used for generating the + summary pages later. + """ + pickle_file = os.path.join(SPHINXROOT, 'function_summary.pkl') + with PickleFile(pickle_file) as pf: + pf.items[fullname] = short_description + + # ----------------------------------------------------------------------- #