From 46b00b49f1e540c054e18b82b86df2c9a64db6bb Mon Sep 17 00:00:00 2001 From: ilv Date: Mon, 19 Nov 2012 16:14:34 +0400 Subject: [PATCH] 0021949: Further improvements in reference documentation Added graphical representation of dependencies between modules and toolkits Add command "wgendoc" to generate occt doxygen documentation Add CHM file generation --- src/WOKTclLib/OCCTDocumentation.tcl | 105 +++++++++++++--- src/WOKTclLib/OCCTDocumentationProcedures.tcl | 119 ++++++++++++++++++ src/WOKTclLib/Wok_Init.tcl | 7 +- 3 files changed, 210 insertions(+), 21 deletions(-) create mode 100644 src/WOKTclLib/OCCTDocumentationProcedures.tcl diff --git a/src/WOKTclLib/OCCTDocumentation.tcl b/src/WOKTclLib/OCCTDocumentation.tcl index 49ba840..6c51e7f 100755 --- a/src/WOKTclLib/OCCTDocumentation.tcl +++ b/src/WOKTclLib/OCCTDocumentation.tcl @@ -1,12 +1,38 @@ +proc wgendoc {workBench {outDir {}} {modules {}} {createChmHelp NO} {hhcLocation ""} {doxygenPath ""} {graphvizPath ""}} { + global env + + if {$workBench == "-help" || $workBench == "-he"} { + puts "Command wgendoc allow you to generate Doxygen documentation" + puts "" + puts "wgendoc {workBench} {outDir} {modules} {createChmHelp} {hhcLocation} {doxygenPath} {graphvizPath}" + puts "Parameters:" + puts " workBench - name of your OCCT workbench" + puts " outDir - documentation output directory" + puts " modules - list of OCCT modules, which documentation will be generated" + puts " createChmHelp - if \"YES\", with HTML files will be generated a CHM documentation file. Default value is \"NO\"." + puts " hhcLocation - if createChmHelp is \"YES\", then you must say, where is HTML Help Workshop directory (which contain file hhc.exe)" + puts " doxygenPath - you can say doxygen.exe directory (if you have latest version of Doxygen). It is optional parameter." + puts " graphvizPath - you can say dot.exe directory (if you have latest version of GraphViz). It is optional parameter." + return + } + + if { "$doxygenPath" == "" } { set doxygenPath "$env(WOKHOME)/3rdparty/win32/utils" } + if { "$graphvizPath" == "" } { set graphvizPath "$env(WOKHOME)/3rdparty/win32/utils" } + + wokcd $workBench + OS -box + OCCDoc_GenerateDoc $outDir $modules $createChmHelp $hhcLocation $doxygenPath $graphvizPath {} {} +} + # general procedure for generation Doxygen documentation # it launches both generation process and post process -proc OCCDoc_GenerateDoc {outDir {modules {}} {doxygenPath {}} {graphvizPath {}} {useSearch YES} {tagFiles {}}} { - catch {exec $doxygenPath/doxygen [OCCDoc_MakeDoxyfile $outDir $modules $graphvizPath]} +proc OCCDoc_GenerateDoc {outDir {modules {}} {createChmHelp NO} {hhcLocation {}} {doxygenPath {}} {graphvizPath {}} {useSearch YES} {tagFiles {}}} { + catch {exec $doxygenPath/doxygen [OCCDoc_MakeDoxyfile $outDir $modules $createChmHelp $hhcLocation $graphvizPath]} OCCDoc_PostProcessor $outDir } # generate Doxygen configuration file for specified OCCT module of toolkit -proc OCCDoc_MakeDoxyfile {outDir {modules {}} {graphvizPath {}} {useSearch YES} {tagFiles {}}} { +proc OCCDoc_MakeDoxyfile {outDir {modules {}} {createChmHelp NO} {hhcLocation {}} {graphvizPath {}} {useSearch YES} {tagFiles {}}} { # by default take all modules if { [llength $modules] <= 0 } { @@ -15,9 +41,13 @@ proc OCCDoc_MakeDoxyfile {outDir {modules {}} {graphvizPath {}} {useSearch YES} # create target directory if { ! [file exists $outDir] } { - mkdir $outDir + file mkdir $outDir } - + + if { ! [file exists $outDir/html] } { + file mkdir $outDir/html + } + # set context set one_module [expr [llength $modules] == 1] if { $one_module } { @@ -85,7 +115,6 @@ proc OCCDoc_MakeDoxyfile {outDir {modules {}} {graphvizPath {}} {useSearch YES} puts $fileid "HIDE_FRIEND_COMPOUNDS = YES" puts $fileid "HIDE_UNDOC_MEMBERS = NO" puts $fileid "INLINE_INFO = YES" - puts $fileid "SHOW_DIRECTORIES = NO" puts $fileid "VERBATIM_HEADERS = NO" puts $fileid "QUIET = YES" puts $fileid "WARNINGS = NO" @@ -99,6 +128,18 @@ proc OCCDoc_MakeDoxyfile {outDir {modules {}} {graphvizPath {}} {useSearch YES} puts $fileid "GENERATE_TAGFILE = ${path_prefix}${name}.tag" puts $fileid "ALLEXTERNALS = NO" puts $fileid "EXTERNAL_GROUPS = NO" + + #chm help file + if { $createChmHelp } { + append hhcLocation "/hhc.exe" + if { [file exists $hhcLocation] } { + puts $fileid "GENERATE_HTMLHELP = YES" + puts $fileid "CHM_FILE = ../${name}HTMLHelp.CHM" + puts $fileid "HHC_LOCATION = \"$hhcLocation\"" + } else { + puts "Can't find $hhcLocation/hhc.exe" + } + } # add tag files for OCCT modules (except current one and depending); # this is based on file Modules.tcl in unit "OS" which defines list of modules @@ -121,8 +162,21 @@ proc OCCDoc_MakeDoxyfile {outDir {modules {}} {graphvizPath {}} {useSearch YES} set graphvizPath $env(GRAPHVIZ_HOME) } if { "$graphvizPath" != "" } { - puts $fileid "HAVE_DOT = YES" - puts $fileid "DOT_PATH = $graphvizPath" + puts $fileid "HAVE_DOT = YES" + puts $fileid "DOT_PATH = $graphvizPath" + #puts $fileid "CLASS_DIAGRAMS = YES" + #puts $fileid "HIDE_UNDOC_RELATIONS = YES" + #puts $fileid "TEMPLATE_RELATIONS = NO" + #puts $fileid "GRAPHICAL_HIERARCHY = YES" + #puts $fileid "DIRECTORY_GRAPH = YES" + puts $fileid "DOT_GRAPH_MAX_NODES = 100" + puts $fileid "INCLUDE_GRAPH = NO" + puts $fileid "INCLUDED_BY_GRAPH = NO" + puts $fileid "DOT_MULTI_TARGETS = YES" + puts $fileid "DOT_IMAGE_FORMAT = png" + puts $fileid "GENERATE_LEGEND = YES" + puts $fileid "DOTFILE_DIRS = $outDir/html" + puts $fileid "DOT_CLEANUP = YES" } else { puts "Warning: DOT is not found; use environment variable GRAPHVIZ_HOME or command argument to specify its location" puts $fileid "HAVE_DOT = NO" @@ -134,10 +188,6 @@ proc OCCDoc_MakeDoxyfile {outDir {modules {}} {graphvizPath {}} {useSearch YES} puts $fileid "INCLUDE_FILE_PATTERNS = *.hxx *.pxx" puts $fileid "EXCLUDE_PATTERNS = */Handle_*.hxx" puts $fileid "SKIP_FUNCTION_MACROS = YES" - puts $fileid "INCLUDE_GRAPH = NO" - puts $fileid "INCLUDED_BY_GRAPH = NO" - puts $fileid "DOT_MULTI_TARGETS = YES" - puts $fileid "DOT_IMAGE_FORMAT = png" puts $fileid "INLINE_SOURCES = NO" # include dirs @@ -148,31 +198,42 @@ proc OCCDoc_MakeDoxyfile {outDir {modules {}} {graphvizPath {}} {useSearch YES} puts $fileid "INCLUDE_PATH = $incdirs" # list of files to generate - set mainpage [OCCDoc_MakeMainPage $outDir/$name.dox $modules] + set mainpage [OCCDoc_MakeMainPage $outDir $outDir/$name.dox $modules] puts $fileid "INPUT = $mainpage \\" foreach header $filelist { puts $fileid " $header \\" - } + } puts $fileid "" - + close $fileid return $filename } # generate main page file describing module structure -proc OCCDoc_MakeMainPage {outFile modules} { - set one_module [expr [llength $modules] == 1] +proc OCCDoc_MakeMainPage {outDir outFile modules} { + + global env + source $env(WOKHOME)/lib/OCCTDocumentationProcedures.tcl + set one_module [expr [llength $modules] == 1] set fd [open $outFile "w"] + + set module_prefix "module_" + set toolkit_prefix "toolkit_" + set package_prefix "package_" + OCCDoc_LoadData + # main page: list of modules if { ! $one_module } { puts $fd "/**" puts $fd "\\mainpage Open CASCADE Technology" foreach mod $modules { - puts $fd "\\li \\subpage [string tolower module_$mod]" + puts $fd "\\li \\subpage [string tolower $module_prefix$mod]" } + # insert modules relationship diagramm + puts $fd "\\dotfile [OCCDoc_CreateModulesDependencyGraph $outDir/html schema_all_modules $modules $module_prefix]" puts $fd "**/\n" } @@ -189,13 +250,15 @@ proc OCCDoc_MakeMainPage {outFile modules} { lappend toolkits $tk puts $fd "\\li \\subpage [string tolower toolkit_$tk]" } + puts $fd "\\dotfile [OCCDoc_CreateModuleToolkitsDependencyGraph $outDir/html schema_$mod $mod $toolkit_prefix]" puts $fd "**/\n" } - + # one page per toolkit: list of packages set packages {} foreach tk $toolkits { puts $fd "/**" + puts $fd "\\dotfile [OCCDoc_CreateToolkitDependencyGraph $outDir/html schema_$tk $tk $toolkit_prefix]" puts $fd "\\page [string tolower toolkit_$tk] Toolkit $tk" foreach pk [lsort [osutils:tk:units [woklocate -u $tk]]] { lappend packages $pk @@ -226,13 +289,14 @@ proc OCCDoc_MakeMainPage {outFile modules} { # puts $fd "/**" # puts $fd "\\class $obj" # puts $fd "Contained in \\ref [string tolower package_$u]" -## puts $fd "\\addtogroup package_$u" +# puts $fd "\\addtogroup package_$u" # puts $fd "**/\n" # } # } # } close $fd + return $outFile } @@ -293,6 +357,7 @@ proc OCCDoc_PostProcessor {outDir} { close $packageFilePnt } + puts "Done" } else { puts "no files found" } diff --git a/src/WOKTclLib/OCCTDocumentationProcedures.tcl b/src/WOKTclLib/OCCTDocumentationProcedures.tcl new file mode 100644 index 0000000..d2bddd1 --- /dev/null +++ b/src/WOKTclLib/OCCTDocumentationProcedures.tcl @@ -0,0 +1,119 @@ +# main graph dependency of modules +proc OCCDoc_CreateModulesDependencyGraph {dir filename modules mpageprefix} { + global module_dependency + + if {![catch {open $dir/$filename.dot "w"} file]} { + puts $file "digraph $filename" + puts $file "\{" + + foreach mod $modules { + puts $file "\t$mod \[ URL = \"$mpageprefix$mod.html\" \]" + foreach mod_depend $module_dependency($mod) { + puts $file "\t$mod_depend -> $mod \[ dir = \"back\", color = \"midnightblue\", style = \"solid\" \]" + } + } + + puts $file "\}" + close $file + + return $filename + } +} + +# dependency of all toolkits in module +proc OCCDoc_CreateModuleToolkitsDependencyGraph {dir filename modulename tpageprefix} { + global toolkits_in_module + global toolkit_dependency + global toolkit_parent_module + + if {![catch {open $dir/$filename.dot "w"} file]} { + puts $file "digraph $filename" + puts $file "\{" + + #vertex + foreach tk $toolkits_in_module($modulename) { + puts $file "\t$tk \[ URL = \"$tpageprefix$tk.html\"\ ]" + foreach tkd $toolkit_dependency($tk) { + if {$toolkit_parent_module($tkd) == $modulename} { + puts $file "\t$tkd -> $tk \[ dir = \"back\", color = \"midnightblue\", style = \"solid\" \]" + } + } + } + + puts $file "\}" + close $file + + return $filename + } +} + +# dependency of current toolkit to other toolkits +proc OCCDoc_CreateToolkitDependencyGraph {dir filename toolkitname tpageprefix} { + global toolkit_dependency + + if {![catch {open $dir/$filename.dot "w"} file]} { + puts $file "digraph $filename" + puts $file "\{" + + puts $file "\t$toolkitname \[ URL = \"$tpageprefix$toolkitname.html\"\, shape = box ]" + foreach tkd $toolkit_dependency($toolkitname) { + puts $file "\t$tkd \[ URL = \"$tpageprefix$tkd.html\"\ , shape = box ]" + puts $file "\t$toolkitname -> $tkd \[ color = \"midnightblue\", style = \"solid\" \]" + } + + puts $file "\}" + close $file + + return $filename + } +} + +# fill arrays of modules, toolkits, dependency of modules/toolkits etc +proc OCCDoc_LoadData {} { + global toolkits_in_module + global toolkit_dependency + global toolkit_parent_module + global module_dependency + + source [woklocate -p OS:source:Modules.tcl] + set modules [OS:Modules] + foreach mod $modules { + source [woklocate -p OS:source:$mod.tcl] + # get toolkits of current module + set toolkits_in_module($mod) [$mod:toolkits] + # get all dependence of current toolkit + foreach tk $toolkits_in_module($mod) { + + # set parent module of current toolkit + set toolkit_parent_module($tk) $mod + #puts "$tk $mod" + + set exlibfile [open [woklocate -p $tk:source:EXTERNLIB] r] + set exlibfile_data [read $exlibfile] + set exlibfile_data [split $exlibfile_data "\n"] + + set toolkit_dependency($tk) {} + foreach dtk $exlibfile_data { + if {[string first TK $dtk 0] == 0} { + lappend toolkit_dependency($tk) $dtk + } + } + close $exlibfile + } + } + + # get modules dependency + foreach mod $modules { + set module_dependency($mod) {} + foreach tk $toolkits_in_module($mod) { + foreach tkd $toolkit_dependency($tk) { + if { $toolkit_parent_module($tkd) != $mod && + [lsearch $module_dependency($mod) $toolkit_parent_module($tkd)] == -1} { + lappend module_dependency($mod) $toolkit_parent_module($tkd) + } + } + } + } +} + + diff --git a/src/WOKTclLib/Wok_Init.tcl b/src/WOKTclLib/Wok_Init.tcl index 9becf73..d472cf9 100755 --- a/src/WOKTclLib/Wok_Init.tcl +++ b/src/WOKTclLib/Wok_Init.tcl @@ -42,6 +42,11 @@ if { [info commands tcl_exit_proc] == "" } { rename wok_exit_proc exit } +#load procedures for occt documentation +source $env(WOKHOME)/lib/OS.tcl +source $env(WOKHOME)/lib/OCCTDocumentation.tcl +source $env(WOKHOME)/lib/OCCTGetVersion.tcl + set tcl_prompt1 {if {[info commands wokcd] != ""} then {puts -nonewline stdout "[wokcd]> "} else {puts -nonewline stdout "tclsh> "}} global WOK_GLOBALS; @@ -58,5 +63,5 @@ set WOK_GLOBALS(source_proc,term) 1 set WOK_GLOBALS(source_proc,emacs) 1 set WOK_GLOBALS(source_proc,tcl) 1 update -set WOK_GLOBALS(wokinterp,tclcommands) "Winfo|finfo|pinfo|screate|sinfo|srm|ucreate|uinfo|umake|urm|w_info|wcreate|wokcd|wokclose|wokinfo|wokparam|wokprofile|wokenv|wrm|wmove|msclear|wprepare|wstore|wintegre|upack|iwok|wsrc|wdrv|wls|wcd|cd" +set WOK_GLOBALS(wokinterp,tclcommands) "Winfo|finfo|pinfo|screate|sinfo|srm|ucreate|uinfo|umake|urm|w_info|wcreate|wokcd|wokclose|wokinfo|wokparam|wokprofile|wokenv|wrm|wmove|msclear|wprepare|wstore|wintegre|upack|iwok|wsrc|wdrv|wls|wcd|cd|wgendoc" update -- 2.39.5