Update doxygen Python generation (Firas Abbas)

git-svn-id: http://gnuradio.org/svn/gnuradio/trunk@10195 221aa14e-8319-0410-a670-987f0aec2ac5

1 files changed, 125 insertions, 67 deletions

diff --git a/gnuradio-core/doc/other/doxypy.py b/gnuradio-core/doc/other/doxypy.py
index 34353b6ac..82fdb6bea 100755
--- a/gnuradio-core/doc/other/doxypy.py
+++ b/gnuradio-core/doc/other/doxypy.py
@@ -15,8 +15,8 @@ add the following lines to your Doxyfile:
 	INPUT_FILTER = "python /path/to/doxypy.py"
 """
 
-__version__ = "0.3rc2"
-__date__ = "18th December 2007"
+__version__ = "0.4.1"
+__date__ = "5th December 2008"
 __website__ = "http://code.foosel.org/doxypy"
 
 __author__ = (
@@ -45,11 +45,19 @@ import re
 from optparse import OptionParser, OptionGroup
 
 class FSM(object):
-	"""	FSM implements a finite state machine. Transitions are given as
-		4-tuples, consisting of an origin state, a target state, a condition
-		for the transition (given as a reference to a function which gets called
-		with a given piece of input) and a pointer to a function to be called
-		upon the execution of the given transition. 
+	"""Implements a finite state machine.
+	
+	Transitions are given as 4-tuples, consisting of an origin state, a target
+	state, a condition for the transition (given as a reference to a function
+	which gets called with a given piece of input) and a pointer to a function
+	to be called upon the execution of the given transition. 
+	"""
+	
+	"""
+	@var transitions holds the transitions
+	@var current_state holds the current state
+	@var current_input holds the current input
+	@var current_transition hold the currently active transition
 	"""
 	
 	def __init__(self, start_state=None, transitions=[]):
@@ -66,7 +74,8 @@ class FSM(object):
 		
 	def makeTransition(self, input):
 		""" Makes a transition based on the given input.
-			@param	input	input to parse by the FSM
+
+		@param	input	input to parse by the FSM
 		"""
 		for transition in self.transitions:
 			[from_state, to_state, condition, callback] = transition
@@ -76,20 +85,23 @@ class FSM(object):
 					self.current_state = to_state
 					self.current_input = input
 					self.current_transition = transition
+					if options.debug:
+						print >>sys.stderr, "# FSM: executing (%s -> %s) for line '%s'" % (from_state, to_state, input)
 					callback(match)
 					return
 
-
 class Doxypy(object):
 	def __init__(self):
-		self.start_single_comment_re = re.compile("^\s*(''')")
+		string_prefixes = "[uU]?[rR]?"
+		
+		self.start_single_comment_re = re.compile("^\s*%s(''')" % string_prefixes)
 		self.end_single_comment_re = re.compile("(''')\s*$")
 		
-		self.start_double_comment_re = re.compile("^\s*(\"\"\")")
+		self.start_double_comment_re = re.compile("^\s*%s(\"\"\")" % string_prefixes)
 		self.end_double_comment_re = re.compile("(\"\"\")\s*$")
 		
-		self.single_comment_re = re.compile("^\s*(''').*(''')\s*$")
-		self.double_comment_re = re.compile("^\s*(\"\"\").*(\"\"\")\s*$")
+		self.single_comment_re = re.compile("^\s*%s(''').*(''')\s*$" % string_prefixes)
+		self.double_comment_re = re.compile("^\s*%s(\"\"\").*(\"\"\")\s*$" % string_prefixes)
 		
 		self.defclass_re = re.compile("^(\s*)(def .+:|class .+:)")
 		self.empty_re = re.compile("^\s*$")
@@ -141,6 +153,7 @@ class Doxypy(object):
 			# other lines
 			["DEFCLASS", "DEFCLASS", self.empty_re.search, self.appendDefclassLine],
 			["DEFCLASS", "DEFCLASS", self.defclass_re.search, self.resetCommentSearch],
+			["DEFCLASS", "DEFCLASS_MULTI", self.multiline_defclass_start_re.search, self.resetCommentSearch],
 			["DEFCLASS", "DEFCLASS_BODY", self.catchall, self.stopCommentSearch],
 			
 			### DEFCLASS_BODY
@@ -155,16 +168,16 @@ class Doxypy(object):
 		]
 		
 		self.fsm = FSM("FILEHEAD", transitions)
+		self.outstream = sys.stdout
 		
 		self.output = []
-		
 		self.comment = []
 		self.filehead = []
 		self.defclass = []
 		self.indent = ""
 
 	def __closeComment(self):
-		""" Appends any open comment block and triggering block to the output. """
+		"""Appends any open comment block and triggering block to the output."""
 		
 		if options.autobrief:
 			if len(self.comment) == 1 \
@@ -179,59 +192,90 @@ class Doxypy(object):
 			self.output.extend(self.defclass)
 
 	def __docstringSummaryToBrief(self, line):
-		"""	Adds \\brief to the docstrings summary line.
+		"""Adds \\brief to the docstrings summary line.
 		
-			A \\brief is prepended, provided no other doxygen command is at the start of the line.
+		A \\brief is prepended, provided no other doxygen command is at the
+		start of the line.
 		"""
 		stripped = line.strip()
 		if stripped and not stripped[0] in ('@', '\\'):
 			return "\\brief " + line
 		else:
 			return line
+	
+	def __flushBuffer(self):
+		"""Flushes the current outputbuffer to the outstream."""
+		if self.output:
+			try:
+				if options.debug:
+					print >>sys.stderr, "# OUTPUT: ", self.output
+				print >>self.outstream, "\n".join(self.output)
+				self.outstream.flush()
+			except IOError:
+				# Fix for FS#33. Catches "broken pipe" when doxygen closes 
+				# stdout prematurely upon usage of INPUT_FILTER, INLINE_SOURCES 
+				# and FILTER_SOURCE_FILES.
+				pass
+		self.output = []
 
 	def catchall(self, input):
-		"""	The catchall-condition, always returns true. """
+		"""The catchall-condition, always returns true."""
 		return True
 	
 	def resetCommentSearch(self, match):
-		""" Restarts a new comment search for a different triggering line.
-			Closes the current commentblock and starts a new comment search.
+		"""Restarts a new comment search for a different triggering line.
+		
+		Closes the current commentblock and starts a new comment search.
 		"""
+		if options.debug:
+			print >>sys.stderr, "# CALLBACK: resetCommentSearch" 
 		self.__closeComment()
 		self.startCommentSearch(match)
 	
 	def startCommentSearch(self, match):
-		""" Starts a new comment search.
-			Saves the triggering line, resets the current comment and saves
-			the current indentation.
+		"""Starts a new comment search.
+		
+		Saves the triggering line, resets the current comment and saves
+		the current indentation.
 		"""
+		if options.debug:
+			print >>sys.stderr, "# CALLBACK: startCommentSearch"
 		self.defclass = [self.fsm.current_input]
 		self.comment = []
 		self.indent = match.group(1)
 	
 	def stopCommentSearch(self, match):
-		""" Stops a comment search.
-			Closes the current commentblock, resets	the triggering line and
-			appends the current line to the output.
+		"""Stops a comment search.
+		
+		Closes the current commentblock, resets	the triggering line and
+		appends the current line to the output.
 		"""
+		if options.debug:
+			print >>sys.stderr, "# CALLBACK: stopCommentSearch" 
 		self.__closeComment()
 		
 		self.defclass = []
 		self.output.append(self.fsm.current_input)
 	
 	def appendFileheadLine(self, match):
-		"""	Appends a line in the FILEHEAD state.
-			Closes the open comment	block, resets it and appends the current line.
+		"""Appends a line in the FILEHEAD state.
+		
+		Closes the open comment	block, resets it and appends the current line.
 		""" 
+		if options.debug:
+			print >>sys.stderr, "# CALLBACK: appendFileheadLine" 
 		self.__closeComment()
 		self.comment = []
 		self.output.append(self.fsm.current_input)
 
 	def appendCommentLine(self, match):
-		"""	Appends a comment line.
-			The comment delimiter is removed from multiline start and ends as
-			well as singleline comments.
+		"""Appends a comment line.
+		
+		The comment delimiter is removed from multiline start and ends as
+		well as singleline comments.
 		"""
+		if options.debug:
+			print >>sys.stderr, "# CALLBACK: appendCommentLine" 
 		(from_state, to_state, condition, callback) = self.fsm.current_transition
 		
 		# single line comment
@@ -266,17 +310,22 @@ class Doxypy(object):
 			self.comment.append(self.fsm.current_input)
 	
 	def appendNormalLine(self, match):
-		""" Appends a line to the output. """
+		"""Appends a line to the output."""
+		if options.debug:
+			print >>sys.stderr, "# CALLBACK: appendNormalLine" 
 		self.output.append(self.fsm.current_input)
 		
 	def appendDefclassLine(self, match):
-		""" Appends a line to the triggering block. """
+		"""Appends a line to the triggering block."""
+		if options.debug:
+			print >>sys.stderr, "# CALLBACK: appendDefclassLine" 
 		self.defclass.append(self.fsm.current_input)
 	
 	def makeCommentBlock(self):
-		""" Indents the current comment block with respect to the current
-			indentation level.
-			@returns a list of indented comment lines
+		"""Indents the current comment block with respect to the current
+		indentation level.
+
+		@returns a list of indented comment lines
 		"""
 		doxyStart = "##"
 		commentLines = self.comment
@@ -288,42 +337,59 @@ class Doxypy(object):
 		return l
 	
 	def parse(self, input):
-		""" Parses a python file given as input string and returns the doxygen-
-			compatible representation.
-			@param	input	the python code to parse
-			@returns the modified python code
+		"""Parses a python file given as input string and returns the doxygen-
+		compatible representation.
+		
+		@param	input	the python code to parse
+		@returns the modified python code
 		""" 
 		lines = input.split("\n")
 		
 		for line in lines:
 			self.fsm.makeTransition(line)
-		
+			
 		if self.fsm.current_state == "DEFCLASS":
 			self.__closeComment()
 		
 		return "\n".join(self.output)
 	
-def loadFile(filename):
-	""" Loads file "filename" and returns the content.
-		@param   filename	The name of the file to load
-		@returns the content of the file.
-	"""
-	f = open(filename, 'r')
-	
-	try:
-		content = f.read()
-		return content
-	finally:
+	def parseFile(self, filename):
+		"""Parses a python file given as input string and returns the doxygen-
+		compatible representation.
+		
+		@param	input	the python code to parse
+		@returns the modified python code
+		""" 
+		f = open(filename, 'r')
+		
+		for line in f:
+			self.parseLine(line.rstrip('\r\n'))
+		if self.fsm.current_state == "DEFCLASS":
+			self.__closeComment()
+			self.__flushBuffer()
 		f.close()
-
+	
+	def parseLine(self, line):
+		"""Parse one line of python and flush the resulting output to the 
+		outstream.
+		
+		@param	line	the python code line to parse
+		"""
+		self.fsm.makeTransition(line)
+		self.__flushBuffer()
+	
 def optParse():
-	""" Parses commandline options. """
+	"""Parses commandline options."""
 	parser = OptionParser(prog=__applicationName__, version="%prog " + __version__)
 	
 	parser.set_usage("%prog [options] filename")
 	parser.add_option("--autobrief",
 		action="store_true", dest="autobrief",
-		help="Use the docstring summary line as \\brief description"
+		help="use the docstring summary line as \\brief description"
+	)
+	parser.add_option("--debug",
+		action="store_true", dest="debug",
+		help="enable debug output on stderr"
 	)
 	
 	## parse options
@@ -337,20 +403,12 @@ def optParse():
 	return filename[0]
 
 def main():
-	""" Opens the file given as first commandline argument and processes it,
-		then prints out the processed file.
+	"""Starts the parser on the file given by the filename as the first 
+	argument on the commandline.
 	"""
 	filename = optParse()
-	
-	try:
-		input = loadFile(filename)
-	except IOError, (errno, msg):
-		print >>sys.stderr, msg
-		sys.exit(-1)
-	
 	fsm = Doxypy()
-	output = fsm.parse(input)
-	print output
+	fsm.parseFile(filename)
 
 if __name__ == "__main__":
-	main()
\ No newline at end of file
+	main()