haskal
/
kicad
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

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.
This commit is contained in:
Wayne Stambaugh 2018-06-12 10:24:59 -04:00
parent 660aed71b4
commit ade3c2b129
3 changed files with 24 additions and 24 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

8
pcbnew/Doxyfile_python
View File

@ -32,7 +32,7 @@ DOXYFILE_ENCODING = UTF-8
# title of most generated pages and in a few other places. # title of most generated pages and in a few other places.
# The default value is: My Project. # 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 # 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 # 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. # also VERBATIM_HEADERS is set to NO.
# The default value is: 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, # Setting the INLINE_SOURCES tag to YES will include the body of functions,
# classes and enums directly into the documentation. # 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. # and usage relations if the target is undocumented or is not a class.
# The default value is: YES. # 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 # 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: # available from the path. This tool is part of Graphviz (see:
@ -2033,7 +2033,7 @@ HIDE_UNDOC_RELATIONS = NO
# set to NO # set to NO
# The default value is: 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 # 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 # to run in parallel. When set to 0 doxygen will base this on the number of

4
pcbnew/Doxyfile_xml
View File

@ -141,7 +141,7 @@ IGNORE_PREFIX =
#--------------------------------------------------------------------------- #---------------------------------------------------------------------------
# Configuration options related to the HTML output # Configuration options related to the HTML output
#--------------------------------------------------------------------------- #---------------------------------------------------------------------------
GENERATE_HTML = NO GENERATE_HTML = NO
HTML_OUTPUT = html HTML_OUTPUT = html
HTML_FILE_EXTENSION = .html HTML_FILE_EXTENSION = .html
HTML_HEADER = HTML_HEADER =
@ -234,7 +234,7 @@ MAN_LINKS = NO
#--------------------------------------------------------------------------- #---------------------------------------------------------------------------
# Configuration options related to the XML output # Configuration options related to the XML output
#--------------------------------------------------------------------------- #---------------------------------------------------------------------------
GENERATE_XML = YES GENERATE_XML = YES
XML_OUTPUT = xml XML_OUTPUT = xml
XML_SCHEMA = XML_SCHEMA =
XML_DTD = XML_DTD =

36
scripting/build_tools/extract_docstrings.py
View File

@ -8,10 +8,10 @@ Usage:
extract-docstrings.py input_py_wrapper.py input_xml_dir output_directory 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 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 output_directory is the directory where output will be written
@ -45,14 +45,14 @@ def my_open_write(dest):
return open(dest, 'w') return open(dest, 'w')
class Doxy2SWIG: class Doxy2SWIG:
"""Converts Doxygen generated XML files into a file containing """Converts Doxygen generated XML files into a file containing
docstrings that can be used by SWIG-1.3.x that have support for 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 feature("docstring"). Once the data is parsed it is stored in
self.pieces. self.pieces.
""" """
def __init__(self, src): def __init__(self, src):
"""Initialize the instance given a source object (file or """Initialize the instance given a source object (file or
filename). filename).
@ -78,14 +78,14 @@ class Doxy2SWIG:
'reimplementedby', 'derivedcompoundref', 'reimplementedby', 'derivedcompoundref',
'basecompoundref') 'basecompoundref')
#self.generics = [] #self.generics = []
def generate(self): def generate(self):
"""Parses the file set in the initialization. The resulting """Parses the file set in the initialization. The resulting
data is stored in `self.pieces`. data is stored in `self.pieces`.
""" """
self.parse(self.xmldoc) self.parse(self.xmldoc)
def parse(self, node): def parse(self, node):
"""Parse a given node. This function in turn calls the """Parse a given node. This function in turn calls the
`parse_<nodeType>` functions which handle the respective `parse_<nodeType>` functions which handle the respective
@ -114,7 +114,7 @@ class Doxy2SWIG:
`do_<tagName>` handers for different elements. If no handler `do_<tagName>` handers for different elements. If no handler
is available the `generic_parse` method is called. All is available the `generic_parse` method is called. All
tagNames specified in `self.ignores` are simply ignored. tagNames specified in `self.ignores` are simply ignored.
""" """
name = node.tagName name = node.tagName
ignores = self.ignores ignores = self.ignores
@ -164,7 +164,7 @@ class Doxy2SWIG:
if pad: if pad:
npiece = len(self.pieces) npiece = len(self.pieces)
if pad == 2: if pad == 2:
self.add_text('\n') self.add_text('\n')
for n in node.childNodes: for n in node.childNodes:
self.parse(n) self.parse(n)
if pad: if pad:
@ -242,7 +242,7 @@ class Doxy2SWIG:
tmp = node.parentNode.parentNode.parentNode tmp = node.parentNode.parentNode.parentNode
compdef = tmp.getElementsByTagName('compounddef')[0] compdef = tmp.getElementsByTagName('compounddef')[0]
cdef_kind = compdef.attributes['kind'].value cdef_kind = compdef.attributes['kind'].value
if prot == 'public': if prot == 'public':
first = self.get_specific_nodes(node, ('definition', 'name')) first = self.get_specific_nodes(node, ('definition', 'name'))
name = first['name'].firstChild.data name = first['name'].firstChild.data
@ -252,7 +252,7 @@ class Doxy2SWIG:
defn = first['definition'].firstChild.data defn = first['definition'].firstChild.data
self.add_text('\n') self.add_text('\n')
self.add_text('%feature("docstring") ') self.add_text('%feature("docstring") ')
anc = node.parentNode.parentNode anc = node.parentNode.parentNode
if cdef_kind in ('file', 'namespace'): if cdef_kind in ('file', 'namespace'):
ns_node = anc.getElementsByTagName('innernamespace') ns_node = anc.getElementsByTagName('innernamespace')
@ -260,7 +260,7 @@ class Doxy2SWIG:
ns_node = anc.getElementsByTagName('compoundname') ns_node = anc.getElementsByTagName('compoundname')
if ns_node: if ns_node:
ns = ns_node[0].firstChild.data 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: else:
self.add_text(' %s "\n%s'%(name, defn)) self.add_text(' %s "\n%s'%(name, defn))
elif cdef_kind in ('class', 'struct'): elif cdef_kind in ('class', 'struct'):
@ -274,7 +274,7 @@ class Doxy2SWIG:
if n not in first.values(): if n not in first.values():
self.parse(n) self.parse(n)
self.add_text(['";', '\n']) self.add_text(['";', '\n'])
def do_definition(self, node): def do_definition(self, node):
data = node.firstChild.data data = node.firstChild.data
self.add_text('%s "\n%s'%(data, 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 """Cleans the list of strings given as `pieces`. It replaces
multiple newlines by a maximum of 2 and returns a new list. multiple newlines by a maximum of 2 and returns a new list.
It also wraps the paragraphs nicely. It also wraps the paragraphs nicely.
""" """
ret = [] ret = []
count = 0 count = 0
@ -367,7 +367,7 @@ class Doxy2SWIG:
def get_python_classes(input_py): def get_python_classes(input_py):
with open(input_py) as f: with open(input_py) as f:
data = f.read() 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) classes = (classname for classname,superclass in classes_supers)
return classes return classes
return [] return []
@ -383,7 +383,7 @@ def main(input_py, input_xml, output_dir):
class_file = "%s/class%s.xml"%(input_xml,classname.replace("_","__")) class_file = "%s/class%s.xml"%(input_xml,classname.replace("_","__"))
swig_file = "%s/%s.i"%(output_dir,classname.lower()) swig_file = "%s/%s.i"%(output_dir,classname.lower())
if os.path.isfile(class_file): if os.path.isfile(class_file):
print "processing:",class_file," ->",swig_file print "processing:",class_file," ->",swig_file
p = Doxy2SWIG(class_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()) f_index.write('%%include "%s.i"\n'% classname.lower())
#else: #else:
# print "ignoring class %s, as %s does not exist" %(classname,class_file) # print "ignoring class %s, as %s does not exist" %(classname,class_file)