OpenCascade/occt
1
0
Fork 0
mirror of https://git.dev.opencascade.org/repos/occt.git synced 2025-04-05 18:16:23 +03:00
Code Packages Releases Activity

0024364: Document system should use local MathJax also

Browse Source 
the new ability choosing of the location of MathJax was introduced
new argument was added to gendoc.bat script
MathJax choice was updated for CHM articles
Minor corrections of documentation
This commit is contained in:
ibs 2014-02-27 18:33:30 +04:00 committed by apn
parent d4faf9e945
commit e8181411e6
2 changed files with 104 additions and 83 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

76
dox/dev_guides/documentation/documentation.md
View File

@ -9,19 +9,15 @@ This document provides practical guidenes for generation and editing of OCCT use
@section OCCT_DM_SECTION_2 Prerequisites @section OCCT_DM_SECTION_2 Prerequisites
In order to generate documentation, you need to have the following software installed.
<b>Tcl/Tk</b> <b>Tcl/Tk</b>
Version 8.5 or 8.6: http://www.tcl.tk/software/tcltk/download.html Version 8.5 or 8.6: http://www.tcl.tk/software/tcltk/download.html
<b>Doxygen</b> <b>Doxygen</b>
Version 1.8.4 or above: http://www.stack.nl/~dimitri/doxygen/download.html Version 1.8.4 or above: http://www.stack.nl/~dimitri/doxygen/download.html
<b>MathJax</b> (used for rendering math formulas in browser). <b>MiKTeX</b> or equivalent tool (only needed for PDF document creation): http://miktex.org/download
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
**Note**: to generate pdf documentation with MiKTeX you should execute gendoc.bat within MiKTeX environment **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 (run gendoc.bat in MiKTeX command promt or update PATH for MiKTeX bin folder). Also in process of pdf generation
@ -32,6 +28,12 @@ MiKTeX can request you to download missing packages if MiKTeX was installed with
If this option is set to "Yes", MiKTeX will download missing packages automatically. 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 @section OCCT_DM_SECTION_2_1 Documentation Generation
Run gendoc.bat from OCCT directory to generate all articles are defined in FILES.txt: Run gendoc.bat from OCCT directory to generate all articles are defined in FILES.txt:
@ -42,42 +44,26 @@ gendoc.bat options:
* -pdf : To generate PDF files (cannot be used with -html); * -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; * -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; * -l=\<document_name\> : Specifies the article caption for a single document;
* -mathjax=\<path\> : Specifies path to non-default MathJAX installation
* -h : Prints help message; * -h : Prints help message;
* -v : Specifies the Verbose mode (info on all script actions is shown). * -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 If you run the command without arguments (like example above) it will generate HTML documentation for all articles defined in FILES.txt.
for all articles are defined into FILES.txt.
**Note**: the generation process generates PDF files for each article, **Note**: the generation process generates PDF files for each article,
but in html case it generates common Html page with references to the ones. but in html case it generates common Html page with references to the ones.
For generation of specific article you need: For generation of specific article specify path to corresponding MarkDown file (paths relative to *dox* subfolder can be given), for instance:
* have it's name with relative path (from \%OCCDIR\%/dox/ to the file) contained in FILES.txt
(is located into \%OCCDIR\%/dox/ directory).
@verbatim % gendoc.bat -html -m=dev_guides/documentation/documentation.md
devs_guid/documentation/documentation.md
@endverbatim
where documentation .md is name of article and devs_guid/documentation/ is relative path of it Multiple files can be separated with comma:
* use this name with -m option in the generation process: % gendoc.bat -html -m=MD_FILE_1,MD_FILE_2
@verbatim To specify an article name with -l option, use quotes to prevent incorrect interpretation of whitespaces:
% gendoc.bat -html -m=devs_guid/documentation/documentation.md
@endverbatim
Multiple files are separated with comma: % gendoc.bat -pdf -m=MD_FILE_1 -l="Label of MD_FILE_1 document"
@verbatim
% gendoc.bat -html -m=MD_FILE_1,MD_FILE_2
@endverbatim
To sepcify a 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
@section OCCT_DM_SECTION_3 Documentation Conventions @section OCCT_DM_SECTION_3 Documentation Conventions
@ -426,33 +412,7 @@ The TOC in the PDF document will be generated automatically.
@subsection OCCT_DM_SECTION_A_9 Formulas @subsection OCCT_DM_SECTION_A_9 Formulas
Formulas within documents will be generated using MathJax tool. Formulas within MarkDown documents can be defined using LaTeX syntax.
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.
Equations can be written by several ways: Equations can be written by several ways:

77
dox/occdoc.tcl
View File

@ -20,7 +20,7 @@ proc OverviewDoc_DetectCasVersion {theCasRoot} {
} }
# Generates Doxygen configuration file for Overview documentation # 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 doxyFile [open $doxyFileName "w"]
set casroot $casDir set casroot $casDir
@ -150,7 +150,7 @@ proc OverviewDoc_MakeDoxyfile {casDir outDir tagFileDir {doxyFileName} {generato
puts $doxyFile "FORMULA_TRANSPARENT = YES" puts $doxyFile "FORMULA_TRANSPARENT = YES"
puts $doxyFile "USE_MATHJAX = YES" puts $doxyFile "USE_MATHJAX = YES"
puts $doxyFile "MATHJAX_FORMAT = HTML-CSS" 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"} { } elseif { $generatorMode == "CHM_ONLY"} {
puts $doxyFile "GENERATE_HTMLHELP = YES" puts $doxyFile "GENERATE_HTMLHELP = YES"
@ -162,7 +162,7 @@ proc OverviewDoc_MakeDoxyfile {casDir outDir tagFileDir {doxyFileName} {generato
puts $doxyFile "FORMULA_TRANSPARENT = YES" puts $doxyFile "FORMULA_TRANSPARENT = YES"
puts $doxyFile "USE_MATHJAX = YES" puts $doxyFile "USE_MATHJAX = YES"
puts $doxyFile "MATHJAX_FORMAT = HTML-CSS" 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"} { } elseif { $generatorMode == "PDF_ONLY"} {
puts $doxyFile "GENERATE_HTMLHELP = NO" puts $doxyFile "GENERATE_HTMLHELP = NO"
@ -224,7 +224,7 @@ proc OverviewDoc_PrintHelpMessage {} {
puts " -hhc : To define path to hhc - chm generator" puts " -hhc : To define path to hhc - chm generator"
puts " : is used with just -chm option" puts " : is used with just -chm option"
puts " -m=<modules_list> : Specifies list of documents to generate." puts " -m=<modules_list> : Specifies list of documents to generate."
puts " If it is not specified, all files, " puts " If it is not specified, all files "
puts " mentioned in FILES.txt are processed." puts " mentioned in FILES.txt are processed."
puts " -l=<document_name> : Specifies the document caption " puts " -l=<document_name> : Specifies the document caption "
puts " for a single document" puts " for a single document"
@ -232,8 +232,9 @@ proc OverviewDoc_PrintHelpMessage {} {
puts " -v : Specifies the Verbose mode" puts " -v : Specifies the Verbose mode"
puts " (info on all script actions is shown)" puts " (info on all script actions is shown)"
puts " -s=<search_mode> : Specifies the Search mode of HTML documents." puts " -s=<search_mode> : Specifies the Search mode of HTML documents."
puts " Can be: none | local | server | external | " puts " Can be: none | local | server | external"
puts " : Can be used only with -html option" puts " : Can be used only with -html option"
puts " -mathjax=<path> : To use local or alternative copy of MathJax"
} }
# Parses command line arguments # Parses command line arguments
@ -509,7 +510,7 @@ proc OverviewDoc_ProcessTex {{texFiles {}} {latexDir} verboseMode} {
} }
# Main procedure for documents compilation # 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 INDIR [file normalize [file dirname [info script]]]
set CASROOT [file normalize [file dirname "$INDIR/../../"]] set CASROOT [file normalize [file dirname "$INDIR/../../"]]
@ -537,10 +538,22 @@ proc OverviewDoc_Main { {docfiles {}} generatorMode docLabel verboseMode searchM
} }
file mkdir $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 # Run tools to compile documents
puts "[clock format [clock seconds] -format {%Y-%m-%d %H:%M}] Generating Doxyfile..." 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 # Run doxygen tool
if { $generatorMode == "HTML_ONLY"} { if { $generatorMode == "HTML_ONLY"} {
@ -648,6 +661,38 @@ proc OverviewDoc_Main { {docfiles {}} generatorMode docLabel verboseMode searchM
} }
} }
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 # A command for User Documentation compilation
proc occdoc {args} { proc occdoc {args} {
# Programm options # Programm options
@ -659,6 +704,9 @@ proc occdoc {args} {
set SEARCH_MODE "none" set SEARCH_MODE "none"
set hhcPath "" set hhcPath ""
set mathjax_location "http://cdn.mathjax.org/mathjax/latest"
set mathjax_js_name "MathJax.js"
global available_docfiles global available_docfiles
global tcl_platform global tcl_platform
global args_names global args_names
@ -758,6 +806,19 @@ proc occdoc {args} {
puts "Error in argument s" puts "Error in argument s"
return 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 { } else {
puts "\nWrong argument: $arg_n" puts "\nWrong argument: $arg_n"
OverviewDoc_PrintHelpMessage OverviewDoc_PrintHelpMessage
@ -777,5 +838,5 @@ proc occdoc {args} {
} }
# Start main activities # 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
} }