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