mirror of
https://git.dev.opencascade.org/repos/occt.git
synced 2025-09-03 14:10:33 +03:00
0024722: Move functionality of WOK command wgendoc to OCCT tool gendoc
Command gendoc improved to: - generate Reference Manual documentation (OCCT classes reference) with option -refman; option -overview can be used for generation of overview documentation; - generate PDF documents for all User Guides automatically (for files listed in FILES_PDF.txt); - check availability of third-party tools (Doxygen, Inkscape etc.) and properly report warnings and errors. - use templates of configuration files for third-party tools instead of their generation. These template files are located in dox/resources folder Tcl scripts are moved from dox folder to adm. Doxygen warnings are eliminated. Moved all auxilary functions to occaux.tcl.
This commit is contained in:
omy
abv
@@ -1,4 +1,4 @@
|
||||
Building 3rd-party libraries on Linux {#dev_guides__building_3rdparty_linux}
|
||||
Building 3rd-party libraries on Linux {#occt_dev_guides__building_3rdparty_linux}
|
||||
=========
|
||||
|
||||
@tableofcontents
|
||||
|
||||
@@ -1,4 +1,4 @@
|
||||
Building 3rd-party libraries on MacOS X {#dev_guides__building_3rdparty_osx}
|
||||
Building 3rd-party libraries on MacOS X {#occt_dev_guides__building_3rdparty_osx}
|
||||
==============================================
|
||||
@tableofcontents
|
||||
|
||||
|
||||
@@ -1,4 +1,4 @@
|
||||
Building 3rd-party libraries on Windows {#dev_guides__building_3rdparty_windows}
|
||||
Building 3rd-party libraries on Windows {#occt_dev_guides__building_3rdparty_windows}
|
||||
==============================================
|
||||
@tableofcontents
|
||||
|
||||
|
||||
@@ -1,4 +1,4 @@
|
||||
Building with Automake {#dev_guides__building__automake}
|
||||
Building with Automake {#occt_dev_guides__building_automake}
|
||||
======================
|
||||
|
||||
This file describes steps to build OCCT libraries from complete source
|
||||
@@ -6,10 +6,10 @@ archive on Linux with GNU build system (Autotools).
|
||||
|
||||
If you are building OCCT from bare sources (as in Git repository), or do some
|
||||
changes affecting CDL files, you need to use WOK to re-generate header files
|
||||
and build scripts / projects. See paragraph 1 \ref dev_guides__building__wok for instructions.
|
||||
and build scripts / projects. See paragraph 1 \ref occt_dev_guides__building_wok for instructions.
|
||||
|
||||
Before building OCCT, you need to install required third-party libraries; see paragraph 1 of
|
||||
\ref dev_guides__building for instructions.
|
||||
\ref occt_dev_guides__building for instructions.
|
||||
|
||||
Note that during compilation by makefiles on some Linux OS on a station with
|
||||
NVIDIA video card you may experience problems because the installation
|
||||
|
||||
@@ -1,4 +1,4 @@
|
||||
Building OCCT from sources {#dev_guides__building}
|
||||
Building OCCT from sources {#occt_dev_guides__building}
|
||||
=========
|
||||
|
||||
In order to build OCCT libraries from these sources for use in your program,
|
||||
@@ -9,24 +9,23 @@ you need to:
|
||||
|
||||
See the following documents for short guide to installation of
|
||||
third-party libraries on different platforms:
|
||||
- \subpage dev_guides__building_3rdparty_windows
|
||||
- \subpage dev_guides__building_3rdparty_linux
|
||||
- \subpage dev_guides__building_3rdparty_osx
|
||||
|
||||
- \subpage occt_dev_guides__building_3rdparty_windows
|
||||
- \subpage occt_dev_guides__building_3rdparty_linux
|
||||
- \subpage occt_dev_guides__building_3rdparty_osx
|
||||
|
||||
2. If you use bare OCCT sources from Git repository or made some changes affecting
|
||||
CDL files or dependencies of OCCT toolkits, you need to update header files generated
|
||||
from \ref dev_guides__cdl "CDL", and regenerate build scripts for your environment using WOK.
|
||||
See \subpage dev_guides__building__wok for details.
|
||||
from \ref occt_dev_guides__cdl "CDL", and regenerate build scripts for your environment using WOK.
|
||||
See \subpage occt_dev_guides__building_wok for details.
|
||||
|
||||
Skip to step 3 if you use complete source package (e.g. official OCCT
|
||||
release) without changes in CDL.
|
||||
|
||||
3. Build using your preferred build tool.
|
||||
- \subpage dev_guides__building__automake "Building on Linux with Autotools"
|
||||
- \subpage dev_guides__building__cmake "Building with CMake (cross-platform)"
|
||||
- \subpage dev_guides__building__code_blocks "Building on Mac OS X with Code::Blocks"
|
||||
- \subpage dev_guides__building__msvc "Building on Windows with MS Visual Studio"
|
||||
- \subpage dev_guides__building__xcode "Building on Mac OS X with Xcode"
|
||||
- \subpage occt_dev_guides__building_automake "Building on Linux with Autotools"
|
||||
- \subpage occt_dev_guides__building_cmake "Building with CMake (cross-platform)"
|
||||
- \subpage occt_dev_guides__building_code_blocks "Building on Mac OS X with Code::Blocks"
|
||||
- \subpage occt_dev_guides__building_msvc "Building on Windows with MS Visual Studio"
|
||||
- \subpage occt_dev_guides__building_xcode "Building on Mac OS X with Xcode"
|
||||
|
||||
The current version of OCCT can be consulted in the file src/Standard/Standard_Version.hxx
|
||||
@@ -1,4 +1,4 @@
|
||||
Building with CMake {#dev_guides__building__cmake}
|
||||
Building with CMake {#occt_dev_guides__building_cmake}
|
||||
===================
|
||||
|
||||
@tableofcontents
|
||||
@@ -10,10 +10,10 @@ required.
|
||||
|
||||
If you are building OCCT from bare sources (as in Git repository), or do some
|
||||
changes affecting CDL files, you need to use WOK to re-generate header files
|
||||
and build scripts / projects. See \ref dev_guides__building__wok for instructions.
|
||||
and build scripts / projects. See \ref occt_dev_guides__building_wok for instructions.
|
||||
|
||||
Before building OCCT, you need to install required third-party libraries; see
|
||||
instructions for your platform in @ref dev_guides__building.
|
||||
instructions for your platform in @ref occt_dev_guides__building.
|
||||
|
||||
## Decide on location of build and install directories.
|
||||
|
||||
|
||||
@@ -1,4 +1,4 @@
|
||||
Building with Code::Blocks on Mac OS X {#dev_guides__building__code_blocks}
|
||||
Building with Code::Blocks on Mac OS X {#occt_dev_guides__building_code_blocks}
|
||||
======================================
|
||||
|
||||
This file describes steps to build OCCT libraries from complete source package
|
||||
@@ -6,10 +6,10 @@ on Mac OS X with Code::Blocks.
|
||||
|
||||
If you are building OCCT from bare sources (as in Git repository), or do some
|
||||
changes affecting CDL files, you need to use WOK to re-generate header files
|
||||
and build scripts / projects. See \ref dev_guides__building__wok for instructions.
|
||||
and build scripts / projects. See \ref occt_dev_guides__building_wok for instructions.
|
||||
|
||||
Before building OCCT, you need to install required third-party libraries; see
|
||||
paragraph 1 of \ref dev_guides__building for details.
|
||||
paragraph 1 of \ref occt_dev_guides__building for details.
|
||||
|
||||
1. Add paths to the mandatory 3rd-party products (Tcl/Tk and FreeType) in file
|
||||
custom.sh located in \<OCCT_ROOT_DIR\>. For this:
|
||||
|
||||
@@ -1,4 +1,4 @@
|
||||
Building with MS Visual C++ {#dev_guides__building__msvc}
|
||||
Building with MS Visual C++ {#occt_dev_guides__building_msvc}
|
||||
===========================
|
||||
|
||||
This file describes steps to build OCCT libraries from complete source
|
||||
@@ -6,10 +6,10 @@ archive on Windows with MS Visual C++.
|
||||
|
||||
If you are building OCCT from bare sources (as in Git repository), or do some
|
||||
changes affecting CDL files, you need to use WOK to re-generate header files
|
||||
and build scripts / projects. See \ref dev_guides__building__wok for instructions.
|
||||
and build scripts / projects. See \ref occt_dev_guides__building_wok for instructions.
|
||||
|
||||
Before building OCCT, you need to install required third-party libraries; see
|
||||
paragraph 1 of \ref dev_guides__building for instructions.
|
||||
paragraph 1 of \ref occt_dev_guides__building for instructions.
|
||||
|
||||
1. Edit file custom.bat to define environment:
|
||||
|
||||
|
||||
@@ -1,11 +1,11 @@
|
||||
Using WOK {#dev_guides__building__wok}
|
||||
Using WOK {#occt_dev_guides__building_wok}
|
||||
=========
|
||||
|
||||
@tableofcontents
|
||||
|
||||
\ref dev_guides__wok "WOK" is a legacy build environment for Open CASCADE Technology.
|
||||
\ref occt_dev_guides__wok "WOK" is a legacy build environment for Open CASCADE Technology.
|
||||
It is required for generation of header files for classes defined with
|
||||
@ref dev_guides__cdl "CDL" ("Cascade Definition Language").
|
||||
@ref occt_dev_guides__cdl "CDL" ("Cascade Definition Language").
|
||||
Also tools for generation of project files for other build systems, and OCCT
|
||||
documentation, are integrated to WOK.
|
||||
|
||||
|
||||
@@ -1,4 +1,4 @@
|
||||
Building with Xcode {#dev_guides__building__xcode}
|
||||
Building with Xcode {#occt_dev_guides__building_xcode}
|
||||
===================
|
||||
|
||||
This file describes steps to build OCCT libraries from complete source package
|
||||
@@ -6,10 +6,10 @@ on Mac OS X with Xcode.
|
||||
|
||||
If you are building OCCT from bare sources (as in Git repository), or do some
|
||||
changes affecting CDL files, you need to use WOK to re-generate header files
|
||||
and build scripts / projects. See \ref dev_guides__building__wok for instructions.
|
||||
and build scripts / projects. See \ref occt_dev_guides__building_wok for instructions.
|
||||
|
||||
Before building OCCT, you need to install required third-party libraries; see
|
||||
paragraph 1 of \ref dev_guides__building for details.
|
||||
paragraph 1 of \ref occt_dev_guides__building for details.
|
||||
|
||||
1. Add paths to the mandatory 3rd-party products (Tcl/Tk and FreeType)
|
||||
in file custom.sh located in \<OCCT_ROOT_DIR\>. For this:
|
||||
|
||||
@@ -1,4 +1,4 @@
|
||||
Component Definition Language (CDL) {#dev_guides__cdl}
|
||||
Component Definition Language (CDL) {#occt_dev_guides__cdl}
|
||||
==============================
|
||||
|
||||
@tableofcontents
|
||||
|
||||
@@ -1,4 +1,4 @@
|
||||
Coding Rules {#dev_guides__coding_rules}
|
||||
Coding Rules {#occt_dev_guides__coding_rules}
|
||||
======================================
|
||||
|
||||
@tableofcontents
|
||||
@@ -238,7 +238,7 @@ Prefer C++ style comments in C++ sources.
|
||||
|
||||
### Commenting out unused code
|
||||
|
||||
Delete unused code instead of commenting it or using #define.
|
||||
Delete unused code instead of commenting it or using \#define.
|
||||
|
||||
### Indentation in sources [MANDATORY]
|
||||
|
||||
@@ -541,7 +541,7 @@ Use *private* fields if future extensions should be disabled.
|
||||
|
||||
### Constants and inlines over defines [MANDATORY]
|
||||
|
||||
Use constant variables (const) and inline functions instead of defines (#define).
|
||||
Use constant variables (const) and inline functions instead of defines (\#define).
|
||||
|
||||
### Avoid explicit numerical values [MANDATORY]
|
||||
|
||||
|
||||
@@ -1,4 +1,4 @@
|
||||
Contribution Workflow {#dev_guides__contribution_workflow}
|
||||
Contribution Workflow {#occt_dev_guides__contribution_workflow}
|
||||
====================================
|
||||
@tableofcontents
|
||||
|
||||
|
||||
@@ -1,4 +1,4 @@
|
||||
Debugging tools and hints {#dev_guides__debug}
|
||||
Debugging tools and hints {#occt_dev_guides__debug}
|
||||
=========================
|
||||
|
||||
@tableofcontents
|
||||
@@ -27,7 +27,7 @@ Note that all these functions accept pointer to variable as <i>void*</i> to allo
|
||||
|
||||
@subsection occt_debug_call_draw Interacting with DRAW
|
||||
|
||||
Open CASCADE Test Harness or @ref user_guides__test_harness "DRAW" provides an extensive set of tools for inspection and analysis of OCCT shapes and geometric objects and is mostly used as environment for prototyping and debugging OCCT-based algorithms.
|
||||
Open CASCADE Test Harness or @ref occt_user_guides__test_harness "DRAW" provides an extensive set of tools for inspection and analysis of OCCT shapes and geometric objects and is mostly used as environment for prototyping and debugging OCCT-based algorithms.
|
||||
|
||||
In some cases the objects to be inspected are available in DRAW as results of DRAW commands. In other cases, however, it is necessary to inspect intermediate objects created by the debugged algorithm. To support this, DRAW provides a set of commands allowing the developer to store intermediate objects directly from the debugger stopped at some point during the program execution (usually at a breakpoint).
|
||||
|
||||
|
||||
@@ -3,16 +3,16 @@
|
||||
|
||||
The following documents provide information on OCCT building, development and testing:
|
||||
|
||||
* @subpage dev_guides__building "Building OCCT from sources"
|
||||
* @subpage dev_guides__documentation "Documentation system"
|
||||
* @subpage dev_guides__coding_rules "Coding Rules"
|
||||
* @subpage dev_guides__contribution_workflow "Contribution Workflow"
|
||||
* @subpage dev_guides__git_guide "Guide to installing and using Git for OCCT development"
|
||||
* @subpage dev_guides__tests "Automatic Testing system"
|
||||
* @subpage dev_guides__debug "Debugging tools and hints"
|
||||
* @subpage occt_dev_guides__building "Building OCCT from sources"
|
||||
* @subpage occt_dev_guides__documentation "Documentation system"
|
||||
* @subpage occt_dev_guides__coding_rules "Coding Rules"
|
||||
* @subpage occt_dev_guides__contribution_workflow "Contribution Workflow"
|
||||
* @subpage occt_dev_guides__git_guide "Guide to installing and using Git for OCCT development"
|
||||
* @subpage occt_dev_guides__tests "Automatic Testing system"
|
||||
* @subpage occt_dev_guides__debug "Debugging tools and hints"
|
||||
|
||||
Two other documents provide details on obsolete technologies used by OCCT,
|
||||
to be removed in future releases:
|
||||
|
||||
* @subpage dev_guides__wok "Workshop Organization Kit (WOK)"
|
||||
* @subpage dev_guides__cdl "Component Definition Language (CDL)"
|
||||
* @subpage occt_dev_guides__wok "Workshop Organization Kit (WOK)"
|
||||
* @subpage occt_dev_guides__cdl "Component Definition Language (CDL)"
|
||||
|
||||
@@ -1,4 +1,4 @@
|
||||
Documentation System {#dev_guides__documentation}
|
||||
Documentation System {#occt_dev_guides__documentation}
|
||||
======================
|
||||
|
||||
@tableofcontents
|
||||
@@ -40,40 +40,52 @@ See \ref OCCT_DM_SECTION_A_9 for more details on inserting mathematical expressi
|
||||
|
||||
@section OCCT_DM_SECTION_2_1 Documentation Generation
|
||||
|
||||
Run *gendoc.bat* from OCCT directory to generate all documents defined in *FILES.txt*:
|
||||
Run command *gendoc* from command prompt (with OCCT directory as current one) to generate OCCT documentation.
|
||||
The synopsis is:
|
||||
|
||||
*gendoc.bat* can be started with the following options:
|
||||
gendoc \[-h\] {-refman|-overview} \[-html|-pdf|-chm\] \[-m=<list of modules>|-ug=<list of docs>\] \[-v\] \[-s=<search_mode>\] \[-mathjax=<path>\]
|
||||
|
||||
Here the options are:
|
||||
|
||||
* <i>-html</i> : Generates HTML files (cannot be used with -pdf);
|
||||
* <i>-pdf</i> : Generates PDF files (cannot be used with -html);
|
||||
* <i>-m=\<modules_list\></i> : Specifies the list of documents to generate. If it is not specified, all files mentioned in *FILES.txt* are processed;
|
||||
* <i>-l=\<document_name\></i> : Specifies the output document title;
|
||||
* <i>-mathjax=\<path\></i> : Specifies the path to a non-default location of MathJAX;
|
||||
* <i>-h</i> : Prints a help message;
|
||||
* <i>-v</i> : Toggles the Verbose mode (info on all script actions is shown).
|
||||
* Choice of documentation to be generated:
|
||||
* <i>-overview</i>: To generate Overview and User Guides (cannot be used with -refman)
|
||||
* <i>-refman</i>: To generate class Reference Manual (cannot be used with -overview)
|
||||
|
||||
If you run the command without arguments (like in the example above) it will generate HTML documentation for all documents defined in *FILES.txt*.
|
||||
* Choice of output format:
|
||||
* <i>-html</i>: To generate HTML files (default, cannot be used with -pdf or -chm)
|
||||
* <i>-pdf</i>: To generate PDF files (cannot be used with -refman, -html, or -chm)
|
||||
* <i>-chm</i>: To generate CHM files (cannot be used with -html or -pdf)
|
||||
|
||||
* Additional options:
|
||||
* <i>-m=\<modules_list\></i>: List of OCCT modules (separated with comma), for generation of Reference Manual
|
||||
* <i>-ug=\<docs_list\></i>: List of MarkDown documents (separated with comma), to use for generation of Overview / User Guides
|
||||
* <i>-mathjax=\<path\></i>: To use local or alternative copy of MathJax
|
||||
* <i>-s=\<search_mode\></i>: Specifies the Search mode of HTML documents; can be: none | local | server | external
|
||||
* <i>-h</i>: Prints this help message
|
||||
* <i>-v</i>: Enables more verbose output
|
||||
|
||||
**Note**
|
||||
|
||||
* In case of a PDF output the utility generates a separate PDF file for each document;
|
||||
* In case of an HTML output the utility generates a common Table of contents containing references to all documents.
|
||||
* In case of PDF output the utility generates a separate PDF file for each document;
|
||||
* In case of HTML output the utility generates a common Table of contents containing references to all documents.
|
||||
* In case of CHM output single CHM file is generated
|
||||
|
||||
**Examples**
|
||||
|
||||
To generate the output for a specific document specify the path to the corresponding MarkDown file (paths relative to *dox* sub-folder can be given), for instance:
|
||||
|
||||
~~~~
|
||||
% gendoc.bat -html -m=dev_guides/documentation/documentation.md
|
||||
> gendoc -overview -ug=dev_guides/documentation/documentation.md
|
||||
~~~~
|
||||
|
||||
Multiple files can be separated with commas:
|
||||
To generate Reference Manual for the whole Open CASCADE Technology library, run:
|
||||
~~~~
|
||||
% gendoc.bat -html -m=MD_FILE_1,MD_FILE_2
|
||||
> gendoc -refman
|
||||
~~~~
|
||||
|
||||
Use quotes to specify an article name with <i>-l</i> option, which helps to prevent incorrect interpretation of white spaces:
|
||||
|
||||
To generate Reference Manual for Foundation Classes and Modeling Data modules only, with search option, run:
|
||||
~~~~
|
||||
% gendoc.bat -pdf -m=MD_FILE_1 -l="Label of MD_FILE_1 document"
|
||||
> gendoc -refman -m=FoundationClasses,ModelingData,ModelingAlgorithms -s=local
|
||||
~~~~
|
||||
|
||||
@section OCCT_DM_SECTION_3 Documentation Conventions
|
||||
|
||||
@@ -1,4 +1,4 @@
|
||||
Guide to installing and using Git for OCCT development {#dev_guides__git_guide}
|
||||
Guide to installing and using Git for OCCT development {#occt_dev_guides__git_guide}
|
||||
=================================
|
||||
|
||||
@tableofcontents
|
||||
@@ -307,7 +307,7 @@ Click on that tab, then click **Add a public key**, and paste the text of the pu
|
||||
> git clone gitolite@git.dev.opencascade.org:occt <path>
|
||||
~~~~~
|
||||
|
||||
where <i><path></i> is the path to the new folder which will be created for the repository.
|
||||
where <i>\<path\></i> is the path to the new folder which will be created for the repository.
|
||||
|
||||
* In TortoiseGit: create a new folder, open it and right-click in the Explorer window, then choose **Git Clone** in the context menu:
|
||||
|
||||
|
||||
@@ -1,4 +1,4 @@
|
||||
Automated Testing System {#dev_guides__tests}
|
||||
Automated Testing System {#occt_dev_guides__tests}
|
||||
======================================
|
||||
|
||||
@tableofcontents
|
||||
@@ -11,7 +11,7 @@ Reading the Introduction is sufficient for OCCT developers to use the test syste
|
||||
|
||||
@subsection testmanual_1_1 Basic Information
|
||||
|
||||
OCCT automatic testing system is organized around DRAW Test Harness @ref user_guides__test_harness "DRAW Test Harness", a console application based on Tcl (a scripting language) interpreter extended by OCCT-related commands.
|
||||
OCCT automatic testing system is organized around DRAW Test Harness @ref occt_user_guides__test_harness "DRAW Test Harness", a console application based on Tcl (a scripting language) interpreter extended by OCCT-related commands.
|
||||
|
||||
Standard OCCT tests are included with OCCT sources and are located in subdirectory *tests* of the OCCT root folder. Other test folders can be included in the test system, e.g. for testing applications based on OCCT.
|
||||
|
||||
@@ -631,12 +631,12 @@ testdiff dir1 dir2 [groupname [gridname]] [options...]
|
||||
Here *dir1* and *dir2* are directories containing logs of two test runs.
|
||||
|
||||
Possible options are:
|
||||
* <i>-save <filename> </i> - saves the resulting log in a specified file (<i>$dir1/diff-$dir2.log</i> by default). HTML log is saved with the same name and extension .html;
|
||||
* <i>-save \<filename\> </i> - saves the resulting log in a specified file (<i>$dir1/diff-$dir2.log</i> by default). HTML log is saved with the same name and extension .html;
|
||||
* <i>-status {same|ok|all}</i> - allows filtering compared cases by their status:
|
||||
* *same* - only cases with same status are compared (default);
|
||||
* *ok* - only cases with OK status in both logs are compared;
|
||||
* *all* - results are compared regardless of status;
|
||||
* <i>-verbose <level> </i> - defines the scope of output data:
|
||||
* <i>-verbose \<level\> </i> - defines the scope of output data:
|
||||
* 1 - outputs only differences;
|
||||
* 2 - additionally outputs the list of logs and directories present in one of directories only;
|
||||
* 3 - (by default) additionally outputs progress messages;
|
||||
|
||||
File diff suppressed because it is too large
Load Diff
Reference in New Issue
Block a user