@section OCCT_DM_SECTION_2 Prerequisites
+In order to generate documentation, you need to have the following software installed.
+
<b>Tcl/Tk</b>
Version 8.5 or 8.6: http://www.tcl.tk/software/tcltk/download.html
<b>Doxygen</b>
Version 1.8.4 or above: http://www.stack.nl/~dimitri/doxygen/download.html
-<b>MathJax</b> (used for rendering math formulas in browser).
-See \ref OCCT_DM_SECTION_A_9 paragraph for more detailed description.
-The latest version: http://www.mathjax.org/download/
-
-<b>MiKTeX</b> or equivalent tool (used for PDF document creation)
-
-Latest version: http://miktex.org/download
+<b>MiKTeX</b> or equivalent tool (only needed for PDF document creation): http://miktex.org/download
**Note**: to generate pdf documentation with MiKTeX you should execute gendoc.bat within MiKTeX environment
(run gendoc.bat in MiKTeX command promt or update PATH for MiKTeX bin folder). Also in process of pdf generation
If this option is set to "Yes", MiKTeX will download missing packages automatically.
+<b>MathJax</b> is used for rendering math formulas in browser (HTML and CHM outputs): http://www.mathjax.org.
+
+By default MathJAX scripts and fonts are taken from http://cdn.mathjax.org/mathjax/latest and no instalation of MathJAX is necessary if Internet is accessible.
+If you need to use OCCT documentation while offline, you can install local copy of MatJAX, see http://www.mathjax.org/download/.
+See \ref OCCT_DM_SECTION_A_9 paragraph for more details on inserting math.
+
@section OCCT_DM_SECTION_2_1 Documentation Generation
Run gendoc.bat from OCCT directory to generate all articles are defined in FILES.txt:
* -pdf : To generate PDF files (cannot be used with -html);
* -m=\<modules_list\> : Specifies list of articles to generate. If it is not specified, all files, mentioned in FILES.txt are processed;
* -l=\<document_name\> : Specifies the article caption for a single document;
+ * -mathjax=\<path\> : Specifies path to non-default MathJAX installation
* -h : Prints help message;
* -v : Specifies the Verbose mode (info on all script actions is shown).
-If you run the command without arguments (like example above) it will generate HTML documentation
-for all articles are defined into FILES.txt.
+If you run the command without arguments (like example above) it will generate HTML documentation for all articles defined in FILES.txt.
**Note**: the generation process generates PDF files for each article,
but in html case it generates common Html page with references to the ones.
-For generation of specific article you need:
- * have it's name with relative path (from \%OCCDIR\%/dox/ to the file) contained in FILES.txt
- (is located into \%OCCDIR\%/dox/ directory).
+For generation of specific article specify path to corresponding MarkDown file (paths relative to *dox* subfolder can be given), for instance:
-@verbatim
-devs_guid/documentation/documentation.md
-@endverbatim
-
-where documentation .md is name of article and devs_guid/documentation/ is relative path of it
-
- * use this name with -m option in the generation process:
-
-@verbatim
-% gendoc.bat -html -m=devs_guid/documentation/documentation.md
-@endverbatim
+ % gendoc.bat -html -m=dev_guides/documentation/documentation.md
-Multiple files are separated with comma:
+Multiple files can be separated with comma:
-@verbatim
-% gendoc.bat -html -m=MD_FILE_1,MD_FILE_2
-@endverbatim
+ % gendoc.bat -html -m=MD_FILE_1,MD_FILE_2
-To sepcify a article name with -l option, use quotes to prevent incorrect interpretation of whitespaces:
+To specify an article name with -l option, use quotes to prevent incorrect interpretation of whitespaces:
-@verbatim
-% gendoc.bat -pdf -m=MD_FILE_1 -l="Label of MD_FILE_1 document"
-@endverbatim
+ % gendoc.bat -pdf -m=MD_FILE_1 -l="Label of MD_FILE_1 document"
@section OCCT_DM_SECTION_3 Documentation Conventions
@subsection OCCT_DM_SECTION_A_9 Formulas
-Formulas within documents will be generated using MathJax tool.
-
-A developer has to specify these parameters in Doxyfile to enable support of MathJax in Doxygen:
-
- USE_MATHJAX = YES
- MATHJAX_FORMAT = HTML-CSS
- MATHJAX_RELPATH = http://cdn.mathjax.org/mathjax/latest
- MATHJAX_EXTENSIONS = TeX/AMSmath TeX/AMSsymbols
-
-To use MathJax tool with the HTML page, it's \<head\> block has to contain
-
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~{.html}
- <script type="text/x-mathjax-config">
- MathJax.Hub.Config({
- tex2jax: {inlineMath: [["$","$"],["\\(","\\)"]]},
- displayAlign: "left"
- });
- </script>
-
- <script type="text/javascript"
- src="http://cdn.mathjax.org/mathjax/latest/MathJax.js?config=TeX-AMS-MML_HTMLorMML">
- </script>
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-First script configures MathJax to understand separator types and to left allign formulas.
-The second script inserts reference to MathJax tool.
-This tool will always be used when the HTML output will be shown.
+Formulas within MarkDown documents can be defined using LaTeX syntax.
Equations can be written by several ways:
}
# Generates Doxygen configuration file for Overview documentation
-proc OverviewDoc_MakeDoxyfile {casDir outDir tagFileDir {doxyFileName} {generatorMode ""} DocFilesList verboseMode searchMode hhcPath} {
+proc OverviewDoc_MakeDoxyfile {casDir outDir tagFileDir {doxyFileName} {generatorMode ""} DocFilesList verboseMode searchMode hhcPath mathjaxLocation} {
set doxyFile [open $doxyFileName "w"]
set casroot $casDir
puts $doxyFile "FORMULA_TRANSPARENT = YES"
puts $doxyFile "USE_MATHJAX = YES"
puts $doxyFile "MATHJAX_FORMAT = HTML-CSS"
- puts $doxyFile "MATHJAX_RELPATH = http://cdn.mathjax.org/mathjax/latest"
+ puts $doxyFile "MATHJAX_RELPATH = ${mathjaxLocation}"
} elseif { $generatorMode == "CHM_ONLY"} {
puts $doxyFile "GENERATE_HTMLHELP = YES"
puts $doxyFile "FORMULA_TRANSPARENT = YES"
puts $doxyFile "USE_MATHJAX = YES"
puts $doxyFile "MATHJAX_FORMAT = HTML-CSS"
- puts $doxyFile "MATHJAX_RELPATH = http://cdn.mathjax.org/mathjax/latest"
+ puts $doxyFile "MATHJAX_RELPATH = ${mathjaxLocation}"
} elseif { $generatorMode == "PDF_ONLY"} {
puts $doxyFile "GENERATE_HTMLHELP = NO"
puts "\nUsage : occdoc \[-h\] \[-html\] \[-pdf\] \[-m=<list of files>\] \[-l=<document name>\] \[-v\] \[-s\]"
puts ""
puts " Options are : "
- puts " -html : To generate HTML files"
- puts " (cannot be used with -pdf or -chm)"
- puts " -pdf : To generate PDF files"
- puts " (cannot be used with -html or chm)"
- puts " -chm : To generate CHM files"
- puts " (cannot be used with -html or pdf)"
- puts " -hhc : To define path to hhc - chm generator"
- puts " : is used with just -chm option"
- puts " -m=<modules_list> : Specifies list of documents to generate."
- puts " If it is not specified, all files, "
- puts " mentioned in FILES.txt are processed."
- puts " -l=<document_name> : Specifies the document caption "
- puts " for a single document"
- puts " -h : Prints help message"
- puts " -v : Specifies the Verbose mode"
- puts " (info on all script actions is shown)"
- puts " -s=<search_mode> : Specifies the Search mode of HTML documents."
- puts " Can be: none | local | server | external | "
- puts " : Can be used only with -html option"
+ puts " -html : To generate HTML files"
+ puts " (cannot be used with -pdf or -chm)"
+ puts " -pdf : To generate PDF files"
+ puts " (cannot be used with -html or chm)"
+ puts " -chm : To generate CHM files"
+ puts " (cannot be used with -html or pdf)"
+ puts " -hhc : To define path to hhc - chm generator"
+ puts " : is used with just -chm option"
+ puts " -m=<modules_list> : Specifies list of documents to generate."
+ puts " If it is not specified, all files "
+ puts " mentioned in FILES.txt are processed."
+ puts " -l=<document_name> : Specifies the document caption "
+ puts " for a single document"
+ puts " -h : Prints help message"
+ puts " -v : Specifies the Verbose mode"
+ puts " (info on all script actions is shown)"
+ puts " -s=<search_mode> : Specifies the Search mode of HTML documents."
+ puts " Can be: none | local | server | external"
+ puts " : Can be used only with -html option"
+ puts " -mathjax=<path> : To use local or alternative copy of MathJax"
}
# Parses command line arguments
}
# Main procedure for documents compilation
-proc OverviewDoc_Main { {docfiles {}} generatorMode docLabel verboseMode searchMode hhcPath} {
+proc OverviewDoc_Main { {docfiles {}} generatorMode docLabel verboseMode searchMode hhcPath mathjaxLocation} {
set INDIR [file normalize [file dirname [info script]]]
set CASROOT [file normalize [file dirname "$INDIR/../../"]]
file delete -force $LATEXDIR
}
file mkdir $LATEXDIR
+
+ # is MathJax HLink?
+ set mathjax_relative_location $mathjaxLocation
+ if { [file isdirectory "$mathjaxLocation"] == 1 } {
+ if { $generatorMode == "HTML_ONLY"} {
+ # related path
+ set mathjax_relative_location [relativePath $HTMLDIR $mathjaxLocation]
+ } elseif { $generatorMode == "CHM_ONLY"} {
+ # absolute path
+ set mathjax_relative_location [file normalize $mathjaxLocation]
+ }
+ }
# Run tools to compile documents
puts "[clock format [clock seconds] -format {%Y-%m-%d %H:%M}] Generating Doxyfile..."
- OverviewDoc_MakeDoxyfile $CASROOT "$OUTDIR/overview" $TAGFILEDIR $DOXYFILE $generatorMode $docfiles $verboseMode $searchMode $hhcPath
+ OverviewDoc_MakeDoxyfile $CASROOT "$OUTDIR/overview" $TAGFILEDIR $DOXYFILE $generatorMode $docfiles $verboseMode $searchMode $hhcPath $mathjax_relative_location
# Run doxygen tool
if { $generatorMode == "HTML_ONLY"} {
}
}
+proc relativePath {thePathFrom thePathTo} {
+ if { [file isdirectory "$thePathFrom"] == 0 } {
+ return ""
+ }
+
+ set aPathFrom [file normalize "$thePathFrom"]
+ set aPathTo [file normalize "$thePathTo"]
+
+ set aCutedPathFrom "${aPathFrom}/dummy"
+ set aRelatedDeepPath ""
+
+ while { "$aCutedPathFrom" != [file normalize "$aCutedPathFrom/.."] } {
+ set aCutedPathFrom [file normalize "$aCutedPathFrom/.."]
+ # does aPathTo contain aCutedPathFrom?
+ regsub -all $aCutedPathFrom $aPathTo "" aPathFromAfterCut
+ if { "$aPathFromAfterCut" != "$aPathTo" } { # if so
+ if { "$aCutedPathFrom" == "$aPathFrom" } { # just go higher, for example, ./somefolder/someotherfolder
+ set aPathTo ".${aPathTo}"
+ } elseif { "$aCutedPathFrom" == "$aPathTo" } { # remove the last "/"
+ set aRelatedDeepPath [string replace $aRelatedDeepPath end end ""]
+ }
+ regsub -all $aCutedPathFrom $aPathTo $aRelatedDeepPath aPathToAfterCut
+ regsub -all "//" $aPathToAfterCut "/" aPathToAfterCut
+ return $aPathToAfterCut
+ }
+ set aRelatedDeepPath "$aRelatedDeepPath../"
+
+ }
+
+ return $thePathTo
+}
+
# A command for User Documentation compilation
proc occdoc {args} {
# Programm options
set SEARCH_MODE "none"
set hhcPath ""
+ set mathjax_location "http://cdn.mathjax.org/mathjax/latest"
+ set mathjax_js_name "MathJax.js"
+
global available_docfiles
global tcl_platform
global args_names
puts "Error in argument s"
return
}
+ } elseif {$arg_n == "mathjax"} {
+ if {![info exists args_values(pdf)]} {
+ set possible_mathjax_loc $args_values(mathjax)
+ if {[file exist [file join $possible_mathjax_loc $mathjax_js_name]]} {
+ set mathjax_location $args_values(mathjax)
+ puts "$mathjax_location"
+ } else {
+ puts "Warning: $mathjax_js_name isn't found in $possible_mathjax_loc."
+ puts " MathJax will be used from $mathjax_location"
+ }
+ } else {
+ puts "Info: MathJax is not used with pdf and will be ignored"
+ }
} else {
puts "\nWrong argument: $arg_n"
OverviewDoc_PrintHelpMessage
}
# Start main activities
- OverviewDoc_Main $DOCFILES $GEN_MODE $DOCLABEL $VERB_MODE $SEARCH_MODE $hhcPath
+ OverviewDoc_Main $DOCFILES $GEN_MODE $DOCLABEL $VERB_MODE $SEARCH_MODE $hhcPath $mathjax_location
}
projects / occt.git / commitdiff