From 96f5a24813f89ee27f0c73abf745502554599b1e Mon Sep 17 00:00:00 2001 From: abv Date: Thu, 10 Jan 2013 10:21:24 +0400 Subject: [PATCH] 0023588: Include reference documentation generated by Doxygen in all products Added documentation generation to OCCT products (command wgendocp) --- collect_binary.bat | 1 + collect_binary.sh | 1 + src/WOKTclLib/OCCTProductsDocumentation.tcl | 554 ++++++++++++++++++++ src/WOKTclLib/Wok_Init.tcl | 1 + 4 files changed, 557 insertions(+) create mode 100644 src/WOKTclLib/OCCTProductsDocumentation.tcl diff --git a/collect_binary.bat b/collect_binary.bat index 890b470..ab2a804 100644 --- a/collect_binary.bat +++ b/collect_binary.bat @@ -375,6 +375,7 @@ xcopy "src\WOKTclLib\nocdlpack.xpm" "%installPath%\lib\" xcopy "src\WOKTclLib\nocdlpack_open.xpm" "%installPath%\lib\" xcopy "src\WOKTclLib\notes.xpm" "%installPath%\lib\" xcopy "src\WOKTclLib\OCCTDocumentation.tcl" "%installPath%\lib\" +xcopy "src\WOKTclLib\OCCTProductsDocumentation.tcl" "%installPath%\lib\" xcopy "src\WOKTclLib\OCCTDocumentationProcedures.tcl" "%installPath%\lib\" xcopy "src\WOKTclLib\OCCTGetVersion.tcl" "%installPath%\lib\" xcopy "src\WOKTclLib\opencascade.gif" "%installPath%\lib\" diff --git a/collect_binary.sh b/collect_binary.sh index 549c92e..5cfda30 100644 --- a/collect_binary.sh +++ b/collect_binary.sh @@ -278,6 +278,7 @@ cp -f src/WOKTclLib/nocdlpack.xpm $installRelatePath/lib/ cp -f src/WOKTclLib/nocdlpack_open.xpm $installRelatePath/lib/ cp -f src/WOKTclLib/notes.xpm $installRelatePath/lib/ cp -f src/WOKTclLib/OCCTDocumentation.tcl $installRelatePath/lib/ +cp -f src/WOKTclLib/OCCTProductsDocumentation.tcl $installRelatePath/lib/ cp -f src/WOKTclLib/OCCTDocumentationProcedures.tcl $installRelatePath/lib/ cp -f src/WOKTclLib/OCCTGetVersion.tcl $installRelatePath/lib/ cp -f src/WOKTclLib/opencascade.gif $installRelatePath/lib/ diff --git a/src/WOKTclLib/OCCTProductsDocumentation.tcl b/src/WOKTclLib/OCCTProductsDocumentation.tcl new file mode 100644 index 0000000..d29447a --- /dev/null +++ b/src/WOKTclLib/OCCTProductsDocumentation.tcl @@ -0,0 +1,554 @@ +#wgendocp +#[-wb=] +#[-m=] +#[-outdir=] +#[-chm] +#[-hhc=] +#[-qthelp=] +#[-doxygen=] +#[-dot=] +#[-tag=] +proc wgendocp {args} { + global env + global args_names + global args_values + + source $env(WOKHOME)/lib/OCCTDocumentationProcedures.tcl + + if {[OCCDoc_ParseArguments $args] == 1} { + return + } + + if {[lsearch $args_names m] == -1} { + puts "Error in argument m, you must type name of module" + return + } + + set useSearch YES + set outDir "[lindex [wokinfo -R] 0]/doc/doxygen" + set createChmHelp NO + set hhcPath "" + set gthelpPath "" + set createQhpHelp NO + set doxygenPath "$env(WOKHOME)/3rdparty/win32/utils/doxygen.exe" + set graphvizPath "$env(WOKHOME)/3rdparty/win32/utils/dot.exe" + set occt_tag_file "" + + OS -box + + foreach arg_n $args_names { + if {$arg_n == "h"} { + puts "usage : wgendocp \[-wb=\] \[-m=\] \[-outdir=\] \[-chm\] + \[-hhc=\] \[-qthelp=\] \[-doxygen=\] \[-dot=\]" + puts "" + puts " Options are : " + puts " -wb= : Name of OCCT Products workbench" + puts " -m= : Documentation will contain this module (to generate docementation for all modules type \"all\"" + puts " -outdir= : Documentation output directory" + puts " -chm : With HTML files will be generated a CHM documentation file" + puts " -hhc= : Path to HTML Help Workshop (hhc.exe)" + puts " -qthelp= : With HTML files will be generated a Qt Help documentation file," + puts " you must type a path to qthelpgenerator.exe" + puts " -doxygen= : Path to Doxygen (doxygen.exe)" + puts " -dot= : Path to GraphViz (dot.exe)" + puts " -tag= : Full name of OCCT tag file, generated by Doxygen" + puts " -all : Generate documentation for all modules" + return + } elseif {$arg_n == "wb"} { + if {$args_values(wb) != "NULL"} { + wokcd $args_values(wb) + } else { + puts "Error in argument wb" + return + } + } elseif {$arg_n == "m"} { + if {$args_values(m) != "NULL"} { + set module $args_values(m) + if {[llength $module] != 1} { + puts "Error in argument m, you must type ONLY one name of module" + return + } + } else { + puts "Error in argument m" + return + } + } elseif {$arg_n == "outdir"} { + if {$args_values(outdir) != "NULL"} { + set outDir $args_values(outdir) + } else { + puts "Error in argument outdir" + return + } + } elseif {$arg_n == "chm"} { + set createChmHelp YES + set useSearch NO + if {[lsearch $args_names hhc] == -1} { + set hhcPath "C:/Program Files/HTML Help Workshop/hhc.exe" + if {[file exists "$hhcPath"] == 0} { + puts "File hhc.exe was not found" + return + } + } + } elseif {$arg_n == "hhc"} { + if {$args_values(hhc) != "NULL"} { + set hhcPath $args_values(hhc) + if {[file exists "$hhcPath"] == 0} { + puts "File hhc.exe was not found" + return + } + } else { + puts "Error in argument hhc" + return + } + } elseif {$arg_n == "qthelp"} { + if {$args_values(qthelp) != "NULL"} { + set gthelpPath $args_values(qthelp) + if {[file exists "$gthelpPath"] == 0} { + puts "File qhelpgenerator.exe was not found" + return + } else { + set createQhpHelp YES + set useSearch NO + } + } else { + puts "Error in argument qthelp" + return + } + } elseif {$arg_n == "doxygen"} { + if {$args_values(doxygen) != "NULL"} { + set doxygenPath $args_values(doxygen) + if {[file exists "$doxygenPath"] == 0} { + puts "File doxygen.exe was not found" + return + } + } else { + puts "Error in argument doxygen" + return + } + } elseif {$arg_n == "dot"} { + if {$args_values(dot) != "NULL"} { + set graphvizPath $args_values(dot) + if {[file exists "$graphvizPath"] == 0} { + puts "File dot.exe was not found" + return + } + } else { + puts "Error in argument dot" + return + } + } elseif {$arg_n == "tag"} { + if {$args_values(tag) != "NULL"} { + set occt_tag_file $args_values(tag) + if {[file exists $occt_tag_file] == 0} { + puts "Tag file $occt_tag_file was not found" + return + } + } else { + puts "Error in argument tag" + return + } + } else { + puts "Unknown argument $arg_n" + return + } + } + +# puts "module=$module" +# puts "outDir=$outDir" +# puts "createChmHelp=$createChmHelp" +# puts "createQhpHelp=$createQhpHelp" +# puts "hhcPath=$hhcPath" +# puts "gthelpPath=$gthelpPath" +# puts "doxygenPath=$doxygenPath" +# puts "graphvizPath=$graphvizPath" +# puts "useSearch=$useSearch" +# puts "occt_tag_file=$occt_tag_file" +# return + + if {[lsearch $args_names m] != -1} { + if {[string tolower $args_values(m)] == "all"} { + set modules [VAS:Products] + foreach mod $modules { + OCC_Products_Doc_GenerateDoc $outDir $mod $createChmHelp $createQhpHelp $hhcPath $gthelpPath $doxygenPath $graphvizPath $useSearch $occt_tag_file + } + return + } + } + + OCC_Products_Doc_GenerateDoc $outDir $module $createChmHelp $createQhpHelp $hhcPath $gthelpPath $doxygenPath $graphvizPath $useSearch $occt_tag_file +} + +# general procedure for generation Doxygen documentation +# it launches both generation process and post process +proc OCC_Products_Doc_GenerateDoc {outDir {modules {}} {createChmHelp NO} {createQhpHelp NO} {hhcLocation {}} {gthelpPath {}} {doxygenPath {}} {graphvizPath {}} {useSearch YES} {tagFiles {}}} { + puts "Generating documentation for module $modules" + append outDir "/$modules" + set doxygen_project_filename [OCC_Products_Doc_MakeDoxyfile $outDir $modules $createChmHelp $createQhpHelp $hhcLocation $gthelpPath $graphvizPath $useSearch $tagFiles] + + puts "Running Doxygen ..." + set dox_return [catch {exec $doxygenPath $doxygen_project_filename > $outDir/doxygen_out.log} dox_err] + + if {$dox_return != 0} { + puts "During the generation of the documentation there were warnings/errors" + if {[llength [split $dox_err "\n"]] > 1} { + puts "Warnings/error messages contain many strings and stored in a log file $outDir/doxygen_warnings_and_errors.log" + set dox_err_file [open "$outDir/doxygen_warnings_and_errors.log" "w"] + puts $dox_err_file $dox_err + close $dox_err_file + } else { + puts $dox_err + } + } + + if {[OCCDoc_PostProcessor $outDir] == 0} { + puts "Done" + puts "Doxygen log file: $outDir/doxygen_out.log" + puts "Start $outDir/html/Index.html to open generated HTML documentation" + if {$createChmHelp == YES} { + puts "CHM file you can find in $outDir" + } + if {$createQhpHelp == YES} { + puts "QCH file you can find in $outDir" + } + } +} + +# generate Doxygen configuration file for specified module of toolkit +proc OCC_Products_Doc_MakeDoxyfile {outDir {modules {}} {createChmHelp NO} {createQhpHelp NO} {hhcLocation {}} {gthelpPath {}} {graphvizPath {}} {useSearch YES} {tagFiles {}}} { + + puts "Creating Doxygen Project File ..." + + # create target directory + file mkdir $outDir + file mkdir $outDir/html + + set title "OCCT [$modules:name]" + set name $modules + + # get list of header files in the specified modules + set filelist {} + foreach module $modules { + if {[lsearch [OS -lm] $module] == -1 } { + puts "Error: no module $module is known in current workbench" + continue + } + foreach tk [$module:toolkits] { + foreach pk [osutils:tk:units [woklocate -u $tk]] { + lappend filelist [uinfo -p -T pubinclude $pk] + } + } + } + + # filter out files Handle_*.hxx and *.lxx + set hdrlist {} + foreach fileset $filelist { + set hdrset {} + foreach hdr $fileset { + if { ! [regexp {Handle_.*[.]hxx} $hdr] && ! [regexp {.*[.]lxx} $hdr] } { + lappend hdrset $hdr + } + } + lappend hdrlist $hdrset + } + set filelist $hdrlist + + # get OCCT version number + set occt_version [OCCTGetVersion] + + set filename "$outDir/$name.Doxyfile" + #msgprint -i -c "WOKStep_DocGenerate:Execute" "Generating Doxygen file for $title in $filename" + set fileid [open $filename "w"] + + set path_prefix "$outDir/" + + puts $fileid "PROJECT_NAME = \"$title\"" + puts $fileid "PROJECT_NUMBER = $occt_version " + puts $fileid "OUTPUT_DIRECTORY = ${path_prefix}." + puts $fileid "CREATE_SUBDIRS = NO" + puts $fileid "OUTPUT_LANGUAGE = English" + puts $fileid "MULTILINE_CPP_IS_BRIEF = YES" + puts $fileid "INHERIT_DOCS = YES" + puts $fileid "REPEAT_BRIEF = NO" + puts $fileid "ALWAYS_DETAILED_SEC = NO" + puts $fileid "INLINE_INHERITED_MEMB = NO" + puts $fileid "FULL_PATH_NAMES = NO" + puts $fileid "OPTIMIZE_OUTPUT_FOR_C = YES" + puts $fileid "SUBGROUPING = YES" + puts $fileid "DISTRIBUTE_GROUP_DOC = YES" + puts $fileid "EXTRACT_ALL = YES" + puts $fileid "EXTRACT_PRIVATE = NO" + puts $fileid "EXTRACT_LOCAL_CLASSES = NO" + puts $fileid "EXTRACT_LOCAL_METHODS = NO" + puts $fileid "HIDE_FRIEND_COMPOUNDS = YES" + puts $fileid "HIDE_UNDOC_MEMBERS = NO" + puts $fileid "INLINE_INFO = YES" + puts $fileid "VERBATIM_HEADERS = NO" + puts $fileid "QUIET = YES" + puts $fileid "WARNINGS = NO" + puts $fileid "ENABLE_PREPROCESSING = YES" + puts $fileid "MACRO_EXPANSION = YES" + puts $fileid "EXPAND_ONLY_PREDEF = YES" + puts $fileid "PREDEFINED = Standard_EXPORT __Standard_API __Draw_API Handle(a):=Handle" + puts $fileid "GENERATE_HTML = YES" + puts $fileid "GENERATE_LATEX = NO" + puts $fileid "SEARCH_INCLUDES = YES" + puts $fileid "SHOW_NAMESPACES = YES" + puts $fileid "GENERATE_TAGFILE = ${path_prefix}${name}.tag" + puts $fileid "ALLEXTERNALS = NO" + puts $fileid "EXTERNAL_GROUPS = NO" + + #chm help file + if { $createChmHelp == YES} { + puts $fileid "GENERATE_HTMLHELP = YES" + puts $fileid "CHM_FILE = ../${name}HTMLHelp.CHM" + puts $fileid "HHC_LOCATION = \"$hhcLocation\"" + } + + #qhp help file + if { $createQhpHelp == YES} { + puts $fileid "GENERATE_QHP = YES" + puts $fileid "QHP_NAMESPACE = \"occt.doxygen.documentation\"" + #puts $fileid "QHP_VIRTUAL_FOLDER = \"${name}_QHP_VF\"" + puts $fileid "QCH_FILE = ../${name}QHPHelp.QCH" + puts $fileid "QHG_LOCATION = \"$gthelpPath\"" + } + + if { $useSearch } { + puts $fileid "SEARCHENGINE = $useSearch" + } + if { "$graphvizPath" != "" } { + puts $fileid "HAVE_DOT = YES" + puts $fileid "DOT_PATH = $graphvizPath" + 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" + } + + puts $fileid "COLLABORATION_GRAPH = NO" + puts $fileid "ENABLE_PREPROCESSING = YES" + puts $fileid "INCLUDE_FILE_PATTERNS = *.hxx *.pxx" + puts $fileid "EXCLUDE_PATTERNS = */Handle_*.hxx" + puts $fileid "SKIP_FUNCTION_MACROS = YES" + puts $fileid "INLINE_SOURCES = NO" + + # add tag files + set tagdir "" + if { [llength $tagFiles] > 0 } { + set tagdef {} + foreach tagfile $tagFiles { + if {[file exists $tagfile] == 1} { + set tagdir "../../../html/" + set tagdef "$tagdef \\\n $tagfile=$tagdir" + } + } + puts $fileid "TAGFILES = $tagdef" + } + + # include dirs + set incdirs "" + foreach wb [w_info -A] { + set incdirs "$incdirs [wokparam -v %${wb}_Home]/inc" + } + puts $fileid "INCLUDE_PATH = $incdirs" + + # list of files to generate + set mainpage [OCC_Products_Doc_MakeMainPage $outDir $outDir/$name.dox $modules $tagdir] + puts $fileid "INPUT = $mainpage \\" + foreach header $filelist { + puts $fileid " $header \\" + } + puts $fileid "" + + close $fileid + + return $filename +} + +proc OCC_Products_Doc_LoadData {} { + global toolkits_in_module + global toolkit_dependency + global toolkit_parent_module + + source [woklocate -p VAS:source:Products.tcl] + set modules [VAS:Products] + foreach mod $modules { + source [woklocate -p VAS: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 toolkit_dependency($tk) {} + if {[file exists [woklocate -p $tk:source:EXTERNLIB]] != 0} { + set exlibfile [open [woklocate -p $tk:source:EXTERNLIB] r] + set exlibfile_data [read $exlibfile] + set exlibfile_data [split $exlibfile_data "\n"] + foreach dtk $exlibfile_data { + if {[string first TK $dtk 0] == 0} { + lappend toolkit_dependency($tk) $dtk + } + } + close $exlibfile + } + } + } +} + +# dependency of current toolkit to other toolkits +proc OCC_Products_Doc_CreateToolkitDependencyGraph {dir filename toolkitname tpageprefix occttagdir} { + global toolkit_dependency + global toolkit_parent_module + + if {![catch {open $dir/$filename.dot "w"} file]} { + puts $file "digraph $filename" + puts $file "\{" + + puts $file "\t$toolkitname \[ URL = \"[string tolower $tpageprefix$toolkitname.html]\"\, shape = box ]" + foreach tkd $toolkit_dependency($toolkitname) { + set td_line "\t$tkd \[ shape = box" + if {[info exists toolkit_parent_module($tkd)] == 0} { + append td_line " , style = filled , fillcolor = \"#DDDDDD\"" + if {$occttagdir != ""} { + append td_line " , URL = \"[string tolower $occttagdir$tpageprefix$tkd.html]\"" + } + } else { + append td_line " , URL = \"[string tolower "../../$toolkit_parent_module($tkd)/html/$tpageprefix$tkd.html"]\"" + } + puts $file "$td_line \]" + puts $file "\t$toolkitname -> $tkd \[ color = \"midnightblue\", style = \"solid\" \]" + } + + if {[llength $toolkit_dependency($toolkitname)] > 1} { + puts $file "\taspect = 1" + } + + puts $file "\}" + close $file + + return $filename + } +} + +proc OCC_Products_Doc_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 = \"[string tolower $tpageprefix$tk.html]\"\ ]" + foreach tkd $toolkit_dependency($tk) { + if {[info exists toolkit_parent_module($tkd)] == 1} { + if {$toolkit_parent_module($tkd) == $modulename} { + puts $file "\t$tkd -> $tk \[ dir = \"back\", color = \"midnightblue\", style = \"solid\" \]" + } + } + } + } + + puts $file "\}" + close $file + + return $filename + } +} + +# generate main page file describing module structure +proc OCC_Products_Doc_MakeMainPage {outDir outFile modules occttagdir} { + + global env + + set one_module [expr [llength $modules] == 1] + set fd [open $outFile "w"] + + set module_prefix "module_" + set toolkit_prefix "toolkit_" + set package_prefix "package_" + + OCC_Products_Doc_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_prefix$mod]" +# } +# # insert modules relationship diagramm +# #puts $fd "\\dotfile [OCCDoc_CreateModulesDependencyGraph $outDir/html schema_all_modules $modules $module_prefix]" +# puts $fd "**/\n" +# } + + # one page per module: list of toolkits + set toolkits {} + foreach mod $modules { + puts $fd "/**" + if { $one_module } { + puts $fd "\\mainpage Module [$mod:name]" + } else { + puts $fd "\\page [string tolower module_$mod] Module [$mod:name]" + } + foreach tk [lsort [$mod:toolkits]] { + lappend toolkits $tk + puts $fd "\\li \\subpage [string tolower toolkit_$tk]" + } + puts $fd "\\dotfile [OCC_Products_Doc_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 "\\page [string tolower toolkit_$tk] Toolkit $tk" + foreach pk [lsort [osutils:tk:units [woklocate -u $tk]]] { + lappend packages $pk + set u [wokinfo -n $pk] + puts $fd "\\li \\subpage [string tolower package_$u]" + } + puts $fd "\\dotfile [OCC_Products_Doc_CreateToolkitDependencyGraph $outDir/html schema_$tk $tk $toolkit_prefix $occttagdir]" + puts $fd "**/\n" + } + + # one page per package: list of classes + foreach pk $packages { + set u [wokinfo -n $pk] + puts $fd "/**" + puts $fd "\\page [string tolower package_$u] Package $u" + foreach hdr [lsort [uinfo -f -T pubinclude $pk]] { + if { ! [regexp {^Handle_} $hdr] && [regexp {(.*)[.]hxx} $hdr str obj] } { + puts $fd "\\li \\subpage $obj" + } + } + puts $fd "**/\n" + } + + # one page per class: set reference to package +# foreach pk $packages { +# set u [wokinfo -n $pk] +# foreach hdr [uinfo -f -T pubinclude $pk] { +# if { ! [regexp {^Handle_} $hdr] && [regexp {(.*)[.]hxx} $hdr str obj] } { +# puts $fd "/**" +# puts $fd "\\class $obj" +# puts $fd "Contained in \\ref [string tolower package_$u]" +# puts $fd "\\addtogroup package_$u" +# puts $fd "**/\n" +# } +# } +# } + + close $fd + + return $outFile +} diff --git a/src/WOKTclLib/Wok_Init.tcl b/src/WOKTclLib/Wok_Init.tcl index d472cf9..87c92ed 100755 --- a/src/WOKTclLib/Wok_Init.tcl +++ b/src/WOKTclLib/Wok_Init.tcl @@ -45,6 +45,7 @@ if { [info commands tcl_exit_proc] == "" } { #load procedures for occt documentation source $env(WOKHOME)/lib/OS.tcl source $env(WOKHOME)/lib/OCCTDocumentation.tcl +source $env(WOKHOME)/lib/OCCTProductsDocumentation.tcl source $env(WOKHOME)/lib/OCCTGetVersion.tcl set tcl_prompt1 {if {[info commands wokcd] != ""} then {puts -nonewline stdout "[wokcd]> "} else {puts -nonewline stdout "tclsh> "}} -- 2.39.5