Chris@4: import os
Chris@4: import os.path
Chris@4: import string
Chris@4: 
Chris@4: paRootDirectory = '../../'
Chris@4: paHtmlDocDirectory = os.path.join( paRootDirectory, "doc", "html" )
Chris@4: 
Chris@4: ## Script to check documentation status
Chris@4: ## this script assumes that html doxygen documentation has been generated
Chris@4: ##
Chris@4: ## it then walks the entire portaudio source tree and check that
Chris@4: ## - every source file (.c,.h,.cpp) has a doxygen comment block containing
Chris@4: ##	- a @file directive
Chris@4: ##	- a @brief directive
Chris@4: ##	- a @ingroup directive
Chris@4: ## - it also checks that a corresponding html documentation file has been generated.
Chris@4: ##
Chris@4: ## This can be used as a first-level check to make sure the documentation is in order.
Chris@4: ##
Chris@4: ## The idea is to get a list of which files are missing doxygen documentation.
Chris@4: 
Chris@4: 
Chris@4: # recurse from top and return a list of all with the given
Chris@4: # extensions. ignore .svn directories. return absolute paths
Chris@4: def recursiveFindFiles( top, extensions, includePaths ):
Chris@4:     result = []
Chris@4:     for (dirpath, dirnames, filenames) in os.walk(top):
Chris@4:         if not '.svn' in dirpath:
Chris@4:             for f in filenames:
Chris@4:                 if os.path.splitext(f)[1] in extensions:
Chris@4:                     if includePaths:
Chris@4:                         result.append( os.path.abspath( os.path.join( dirpath, f ) ) )
Chris@4:                     else:
Chris@4:                         result.append( f )
Chris@4:     return result
Chris@4: 
Chris@4: # generate the html file name that doxygen would use for
Chris@4: # a particular source file. this is a brittle conversion
Chris@4: # which i worked out by trial and error
Chris@4: def doxygenHtmlDocFileName( sourceFile ):
Chris@4:     return sourceFile.replace( '_', '__' ).replace( '.', '_8' ) + '.html'
Chris@4: 
Chris@4: 
Chris@4: sourceFiles = recursiveFindFiles( paRootDirectory, [ '.c', '.h', '.cpp' ], True );
Chris@4: docFiles = recursiveFindFiles( paHtmlDocDirectory, [ '.html' ], False );
Chris@4: 
Chris@4: 
Chris@4: 
Chris@4: currentFile = ""
Chris@4: 
Chris@4: def printError( f, message ):
Chris@4:     global currentFile
Chris@4:     if f != currentFile:
Chris@4:         currentFile = f
Chris@4:         print f, ":"
Chris@4:     print "\t!", message
Chris@4: 
Chris@4: 
Chris@4: for f in sourceFiles:
Chris@4:     if not doxygenHtmlDocFileName( os.path.basename(f) ) in docFiles:
Chris@4:         printError( f, "no doxygen generated doc page" )
Chris@4: 
Chris@4:     s = file( f, 'rt' ).read()
Chris@4: 
Chris@4:     if not '/**' in s:
Chris@4:         printError( f, "no doxygen /** block" )  
Chris@4:     
Chris@4:     if not '@file' in s:
Chris@4:         printError( f, "no doxygen @file tag" )
Chris@4: 
Chris@4:     if not '@brief' in s:
Chris@4:         printError( f, "no doxygen @brief tag" )
Chris@4:         
Chris@4:     if not '@ingroup' in s:
Chris@4:         printError( f, "no doxygen @ingroup tag" )
Chris@4:         
Chris@4: