From ade3c2b12921a01360c75ad7e5a77371ae6d4f0e Mon Sep 17 00:00:00 2001 From: Wayne Stambaugh Date: Tue, 12 Jun 2018 10:24:59 -0400 Subject: [PATCH] Minor Python scripting documentation fixes. Change the Doxyfile project name from KiCAD to KiCad. It doesn't look very good when we don't get the project name capitalization correct. Clean up trailing whitespace in some of the helper scripts and Doxyfile. --- pcbnew/Doxyfile_python | 8 ++--- pcbnew/Doxyfile_xml | 4 +-- scripting/build_tools/extract_docstrings.py | 36 ++++++++++----------- 3 files changed, 24 insertions(+), 24 deletions(-) diff --git a/pcbnew/Doxyfile_python b/pcbnew/Doxyfile_python index 5093cf0172..8854efbe43 100644 --- a/pcbnew/Doxyfile_python +++ b/pcbnew/Doxyfile_python @@ -32,7 +32,7 @@ DOXYFILE_ENCODING = UTF-8 # title of most generated pages and in a few other places. # The default value is: My Project. -PROJECT_NAME = "KiCAD pcbnew scripting" +PROJECT_NAME = "KiCad Pcbnew Python Scripting" # The PROJECT_NUMBER tag can be used to enter a project or revision number. This # could be handy for archiving the generated documentation or if some version @@ -883,7 +883,7 @@ USE_MDFILE_AS_MAINPAGE = # also VERBATIM_HEADERS is set to NO. # The default value is: NO. -SOURCE_BROWSER = YES +SOURCE_BROWSER = YES # Setting the INLINE_SOURCES tag to YES will include the body of functions, # classes and enums directly into the documentation. @@ -2024,7 +2024,7 @@ MSCGEN_PATH = # and usage relations if the target is undocumented or is not a class. # The default value is: YES. -HIDE_UNDOC_RELATIONS = NO +HIDE_UNDOC_RELATIONS = NO # If you set the HAVE_DOT tag to YES then doxygen will assume the dot tool is # available from the path. This tool is part of Graphviz (see: @@ -2033,7 +2033,7 @@ HIDE_UNDOC_RELATIONS = NO # set to NO # The default value is: NO. -HAVE_DOT = YES +HAVE_DOT = YES # The DOT_NUM_THREADS specifies the number of dot invocations doxygen is allowed # to run in parallel. When set to 0 doxygen will base this on the number of diff --git a/pcbnew/Doxyfile_xml b/pcbnew/Doxyfile_xml index 189b5a1e44..4fcdfd0bad 100644 --- a/pcbnew/Doxyfile_xml +++ b/pcbnew/Doxyfile_xml @@ -141,7 +141,7 @@ IGNORE_PREFIX = #--------------------------------------------------------------------------- # Configuration options related to the HTML output #--------------------------------------------------------------------------- -GENERATE_HTML = NO +GENERATE_HTML = NO HTML_OUTPUT = html HTML_FILE_EXTENSION = .html HTML_HEADER = @@ -234,7 +234,7 @@ MAN_LINKS = NO #--------------------------------------------------------------------------- # Configuration options related to the XML output #--------------------------------------------------------------------------- -GENERATE_XML = YES +GENERATE_XML = YES XML_OUTPUT = xml XML_SCHEMA = XML_DTD = diff --git a/scripting/build_tools/extract_docstrings.py b/scripting/build_tools/extract_docstrings.py index 103654e11f..86e60f006c 100644 --- a/scripting/build_tools/extract_docstrings.py +++ b/scripting/build_tools/extract_docstrings.py @@ -8,10 +8,10 @@ Usage: extract-docstrings.py input_py_wrapper.py input_xml_dir output_directory -input_py_wrapper.py is a swig generated file, with/without docstrings, +input_py_wrapper.py is a swig generated file, with/without docstrings, so we can get to know which classes are inspected by swig - -input_xml_dir is your doxygen generated XML directory + +input_xml_dir is your doxygen generated XML directory output_directory is the directory where output will be written @@ -45,14 +45,14 @@ def my_open_write(dest): return open(dest, 'w') -class Doxy2SWIG: +class Doxy2SWIG: """Converts Doxygen generated XML files into a file containing docstrings that can be used by SWIG-1.3.x that have support for feature("docstring"). Once the data is parsed it is stored in self.pieces. - """ - + """ + def __init__(self, src): """Initialize the instance given a source object (file or filename). @@ -78,14 +78,14 @@ class Doxy2SWIG: 'reimplementedby', 'derivedcompoundref', 'basecompoundref') #self.generics = [] - + def generate(self): """Parses the file set in the initialization. The resulting data is stored in `self.pieces`. """ self.parse(self.xmldoc) - + def parse(self, node): """Parse a given node. This function in turn calls the `parse_` functions which handle the respective @@ -114,7 +114,7 @@ class Doxy2SWIG: `do_` handers for different elements. If no handler is available the `generic_parse` method is called. All tagNames specified in `self.ignores` are simply ignored. - + """ name = node.tagName ignores = self.ignores @@ -164,7 +164,7 @@ class Doxy2SWIG: if pad: npiece = len(self.pieces) if pad == 2: - self.add_text('\n') + self.add_text('\n') for n in node.childNodes: self.parse(n) if pad: @@ -242,7 +242,7 @@ class Doxy2SWIG: tmp = node.parentNode.parentNode.parentNode compdef = tmp.getElementsByTagName('compounddef')[0] cdef_kind = compdef.attributes['kind'].value - + if prot == 'public': first = self.get_specific_nodes(node, ('definition', 'name')) name = first['name'].firstChild.data @@ -252,7 +252,7 @@ class Doxy2SWIG: defn = first['definition'].firstChild.data self.add_text('\n') self.add_text('%feature("docstring") ') - + anc = node.parentNode.parentNode if cdef_kind in ('file', 'namespace'): ns_node = anc.getElementsByTagName('innernamespace') @@ -260,7 +260,7 @@ class Doxy2SWIG: ns_node = anc.getElementsByTagName('compoundname') if ns_node: ns = ns_node[0].firstChild.data - self.add_text(' %s::%s "\n%s'%(ns, name, defn)) + self.add_text(' %s::%s "\n%s'%(ns, name, defn)) else: self.add_text(' %s "\n%s'%(name, defn)) elif cdef_kind in ('class', 'struct'): @@ -274,7 +274,7 @@ class Doxy2SWIG: if n not in first.values(): self.parse(n) self.add_text(['";', '\n']) - + def do_definition(self, node): data = node.firstChild.data self.add_text('%s "\n%s'%(data, data)) @@ -332,7 +332,7 @@ class Doxy2SWIG: """Cleans the list of strings given as `pieces`. It replaces multiple newlines by a maximum of 2 and returns a new list. It also wraps the paragraphs nicely. - + """ ret = [] count = 0 @@ -367,7 +367,7 @@ class Doxy2SWIG: def get_python_classes(input_py): with open(input_py) as f: data = f.read() - classes_supers = re.findall(r'class[ ]+([\w_]+)(\([\w_, ]+\))?:',data) + classes_supers = re.findall(r'class[ ]+([\w_]+)(\([\w_, ]+\))?:',data) classes = (classname for classname,superclass in classes_supers) return classes return [] @@ -383,7 +383,7 @@ def main(input_py, input_xml, output_dir): class_file = "%s/class%s.xml"%(input_xml,classname.replace("_","__")) swig_file = "%s/%s.i"%(output_dir,classname.lower()) - + if os.path.isfile(class_file): print "processing:",class_file," ->",swig_file p = Doxy2SWIG(class_file) @@ -392,7 +392,7 @@ def main(input_py, input_xml, output_dir): f_index.write('%%include "%s.i"\n'% classname.lower()) #else: # print "ignoring class %s, as %s does not exist" %(classname,class_file) - +