|
cannam@89
|
1 import os
|
|
cannam@89
|
2 import os.path
|
|
cannam@89
|
3 import string
|
|
cannam@89
|
4
|
|
cannam@89
|
5 paRootDirectory = '../../'
|
|
cannam@89
|
6 paHtmlDocDirectory = os.path.join( paRootDirectory, "doc", "html" )
|
|
cannam@89
|
7
|
|
cannam@89
|
8 ## Script to check documentation status
|
|
cannam@89
|
9 ## this script assumes that html doxygen documentation has been generated
|
|
cannam@89
|
10 ##
|
|
cannam@89
|
11 ## it then walks the entire portaudio source tree and check that
|
|
cannam@89
|
12 ## - every source file (.c,.h,.cpp) has a doxygen comment block containing
|
|
cannam@89
|
13 ## - a @file directive
|
|
cannam@89
|
14 ## - a @brief directive
|
|
cannam@89
|
15 ## - a @ingroup directive
|
|
cannam@89
|
16 ## - it also checks that a corresponding html documentation file has been generated.
|
|
cannam@89
|
17 ##
|
|
cannam@89
|
18 ## This can be used as a first-level check to make sure the documentation is in order.
|
|
cannam@89
|
19 ##
|
|
cannam@89
|
20 ## The idea is to get a list of which files are missing doxygen documentation.
|
|
cannam@89
|
21
|
|
cannam@89
|
22
|
|
cannam@89
|
23 # recurse from top and return a list of all with the given
|
|
cannam@89
|
24 # extensions. ignore .svn directories. return absolute paths
|
|
cannam@89
|
25 def recursiveFindFiles( top, extensions, includePaths ):
|
|
cannam@89
|
26 result = []
|
|
cannam@89
|
27 for (dirpath, dirnames, filenames) in os.walk(top):
|
|
cannam@89
|
28 if not '.svn' in dirpath:
|
|
cannam@89
|
29 for f in filenames:
|
|
cannam@89
|
30 if os.path.splitext(f)[1] in extensions:
|
|
cannam@89
|
31 if includePaths:
|
|
cannam@89
|
32 result.append( os.path.abspath( os.path.join( dirpath, f ) ) )
|
|
cannam@89
|
33 else:
|
|
cannam@89
|
34 result.append( f )
|
|
cannam@89
|
35 return result
|
|
cannam@89
|
36
|
|
cannam@89
|
37 # generate the html file name that doxygen would use for
|
|
cannam@89
|
38 # a particular source file. this is a brittle conversion
|
|
cannam@89
|
39 # which i worked out by trial and error
|
|
cannam@89
|
40 def doxygenHtmlDocFileName( sourceFile ):
|
|
cannam@89
|
41 return sourceFile.replace( '_', '__' ).replace( '.', '_8' ) + '.html'
|
|
cannam@89
|
42
|
|
cannam@89
|
43
|
|
cannam@89
|
44 sourceFiles = recursiveFindFiles( paRootDirectory, [ '.c', '.h', '.cpp' ], True );
|
|
cannam@89
|
45 docFiles = recursiveFindFiles( paHtmlDocDirectory, [ '.html' ], False );
|
|
cannam@89
|
46
|
|
cannam@89
|
47
|
|
cannam@89
|
48
|
|
cannam@89
|
49 currentFile = ""
|
|
cannam@89
|
50
|
|
cannam@89
|
51 def printError( f, message ):
|
|
cannam@89
|
52 global currentFile
|
|
cannam@89
|
53 if f != currentFile:
|
|
cannam@89
|
54 currentFile = f
|
|
cannam@89
|
55 print f, ":"
|
|
cannam@89
|
56 print "\t!", message
|
|
cannam@89
|
57
|
|
cannam@89
|
58
|
|
cannam@89
|
59 for f in sourceFiles:
|
|
cannam@89
|
60 if not doxygenHtmlDocFileName( os.path.basename(f) ) in docFiles:
|
|
cannam@89
|
61 printError( f, "no doxygen generated doc page" )
|
|
cannam@89
|
62
|
|
cannam@89
|
63 s = file( f, 'rt' ).read()
|
|
cannam@89
|
64
|
|
cannam@89
|
65 if not '/**' in s:
|
|
cannam@89
|
66 printError( f, "no doxygen /** block" )
|
|
cannam@89
|
67
|
|
cannam@89
|
68 if not '@file' in s:
|
|
cannam@89
|
69 printError( f, "no doxygen @file tag" )
|
|
cannam@89
|
70
|
|
cannam@89
|
71 if not '@brief' in s:
|
|
cannam@89
|
72 printError( f, "no doxygen @brief tag" )
|
|
cannam@89
|
73
|
|
cannam@89
|
74 if not '@ingroup' in s:
|
|
cannam@89
|
75 printError( f, "no doxygen @ingroup tag" )
|
|
cannam@89
|
76
|
|
cannam@89
|
77
|
