View Issue Details

Jump to NotesJump to History
IDProjectCategoryView StatusDate SubmittedLast Update
0021949Open CASCADEOCCT:Documentationpublic2010-08-04 13:422013-04-29 15:21
ReporterabvAssigned Tobugmaster  
PrioritynormalSeverityfeature 
Status closedResolutionfixed 
OSAll 
Target Version6.6.0Fixed in Version6.6.0 
Summary0021949: Further improvements in reference documentation
DescriptionThis record is created to collect ideas, remarks, and proposals for possible
further improvements of OCCT reference documentation (one generated with
Doxygen) after integration of OCC21674.

First, the list of items recorded in OCC21674 but not yet completed:

- Lack of references from entity (class or enum) documentation to package. Note
that this is regression from previous version.

- Eliminate descriptions of operators new() / delete() in classes

- Add graphical representation of dependencies between modules and toolkits

- Generate CHM help

Some remarks from SZV:

- In hierarchy diagrams for some classes (e.g. BRepBuilderAPI_MakeShape -- see
in ModelingAlgorithms / TKTopAlgo) not all subclasses are shown (see red
squares)

- Absence of list of all packages in the module (as it was in previous version)
Additional information
and documentation updates		Overview needs to be updated to describe new command for generation of Doxygen Documentation. In WOK prompt:

:LOC:dev:occt> wgendoc -h
usage : wgendoc [-wb=<workbench name>] [-m=<list of modules>] [-outdir=<path>] [-chm] [-hhc=<path to hhc.exe>] [-qthelp=<path to qhelpgenerator>] [-doxygen=<path to doxygen>] [-dot=<path to dot>]

  Options are :
    -wb=<workbench name> : Name of OCCT workbench (current one by default)
    -m=<list of modules> : Documentation will contain this list of modules
    -outdir=<path> : Documentation output directory
    -chm : Generate CHM file
    -hhc=<path> : Path to HTML Help Compiler (hhc.exe) or equivalent
    -qthelp=<path> : Generate Qt Help file, specify path to qthelpgenerator executable
    -doxygen=<path> : Path to Doxygen executable
    -dot=<path> : Path to GraphViz dot executable

All arguments are optional, by default this command generates HTML documentation for whole OCCT in subfolder "documentation", using Doxygen and Dot executables included with the WOK binaries.
TagsNo tags attached.
Test case numberNot needed

Relationships

child of 0023602 closedbugmaster Qt Help file in reference documentation 

Activities

ilv

2012-11-13 15:47

developer   ~0022226

1) I added a new command to generate documentation

wgendoc {workBench {outDir {}} {modules {}} {createChmHelp NO} {hhcLocation ""} {doxygenPath ""} {graphvizPath ""}}

Please, use latest versions of doxygen (I use doxygen v1.8.2 and graphviz v2.28)
Warning: if you set createChmHelp to "YES", then in HTML-pages will not be search bar. And if you set createChmHelp to "YES", you must specify the directory of HTML Help Workshop.

example of use command:

create documentation of module Draw in directory C:/doc with chm help, using latest version of doxygen and graphviz
wgendoc occt C:/doc {Draw} {YES} {C:/Program Files/HTML Help Workshop} {D:/Devtools/doxygen/bin} {D:/Devtools/graphviz/bin}

create all OCCT documentation without chm file
wgendoc occt C:/doc {} {NO} {} {D:/Devtools/doxygen/bin} {D:/Devtools/graphviz/bin}

2) In documentation I added graphical representation of dependencies between modules, toolkits in current module, and between current toolkits and other toolkits.

3) In hierarchy of diagrams for some classes (e.g. BRepBuilderAPI_MakeShape) not all subclasses are shown, because doxygen cuts graph if number of verticles more than DOT_GRAPH_MAX_NODES. I set it to 100.

This changes are in CR21949_1 branch, please, review my code.

abv

2012-11-19 12:30

manager   ~0022294

I have no remarks, and suggest this new functionality should be included in new WOK 6.6.0 beta and then tested.

abv

2012-11-22 16:15

manager   ~0022360

Last edited: 2012-11-22 17:40

 Please improve interface of command wgendoc as follows:

1. Provide error message if doxygen.exe, dot.exe, or hhc.exe cannot be found by specified path. Also capture output of doxygen to log file, for the user to be able to check what problems have been encountered. Personally I could not get graphs generated and suspect that it is due to wrong path or version of dot.exe, but I have no output to verify this or know what is wrong.

2. At the end message ("Done"), add indication for location of the index.html for the generated HTML documentation (as well as path to CHM file if generated)

3. Add possibility to generate Qt Help projects (should work the same as CHM)

4. As path where HTML Help Workshop is located seems to be quite standard, the command can get it without requiring the user to indicate the path to hhc.exe. Thus indication of this path can be optional. By the way, on my machine hhc.exe failed for whole OCCT complaining for insufficient memory; please check your system to confirm whether it is possible to generate CHM for the whole OCCT at all.

5. Use keywords for specifying command options instead of fixed position. By default, it can use current workbench and generate documents in default location, e.g. doc subfolder. Thus all arguments can be optional. Here is proposed synopsis:

> wgenproj [-wb=<workbench name>] [-outdir=<path>] [-chm] [-qhp] [-hhc=<path to hhc.exe>] [-qthelp=<path to Qt>] [-doxygen=<path to doxygen.exe>] [-dot=<path to dot.exe>]

6. Add keyword -h to get help, as for other WOK commands:

> wgenproj -h
... should print synopsis as above, with explanation of options

ilv

2012-11-29 10:39

developer   ~0022430

Syntax of arguments line changed (like string "-arg=value")
Added messages ("done", directories of generated files , errors)
Doxygen output puts to log file.
Changed synopsis of command (-h).

I added new issue for Qt help file, 23602.

Please, review my changes.

ilv

2012-11-29 10:49

developer   ~0022431

Examples
wgendoc -h
wgendoc -wb=occt -m="Draw" -chm
wgendoc -m="Draw" -outdir="C:/doc"

abv

2012-12-03 17:50

manager   ~0022528

Some remarks:

1. On my workstation (Windows 7 64-bit) path to htmlhelp.exe is not found (use environment variable "ProgramFiles(x86)"). Trying to specify this path explicitly, I get error:

Draw[]> wgendoc -m=Draw -chm {-hhc=c:/Program Files x86/HTML Help Workshop/hhc.exe}
Error in arguments

2. Since -qhp option does not work for the moment, I suggest it should be hidden in the help.
- If -qhp always requires -qthelp, keep only one option

3. Please change message
"File Index.html you can find in d:/occt/doc/draw/html/"
to
"Start d:/occt/doc/draw/html/Index.html to open generated HTML documentation"

4. In arguments specifying paths (-hhc, -qthelp, -doxygen, -dot) it is desirable to use the same approach: either this should be path to the file, or to a contained directory. This seems to be not the case now

ilv

2012-12-05 17:18

developer   ~0022573

Now you must type full path to file (in arguments -hhc, -qthelp, -doxygen, -dot)
Please, review my code

abv

2012-12-06 18:08

manager   ~0022600

Last edited: 2012-12-06 18:55

 I have fixed some issues in CR21949. Error messages are improved; default location of dot.exe and hhc.exe corrected; paths to files in arguments now can specify either directory or a file.

Some problems are still there:

- generated CHM files do not show images (graphs). I have tried using GIF instead of PNG -- no effect

- QCH file is generated successfuilly only when I specify -qthelp=g:/occt-3rdparty/qt462-vc9-32/bin/qhelpgenerator.exe; other builds of Qt that I tried do not work, and no errors are reported. Note that I use doxygen 1.7.4, as 1.8.2 is said to contain bug for QtHelp. My next problem is that I cannot make use of the generated QCH file...

- with the new restriction on the size of graphs in toolkit pages these graphs become greater in vertical direction; for this reason I propose that they should be moved to be after the list of packages on the page

- the tool should report error on unrecognized arguments (e.g. -qhp)

ilv

2012-12-10 10:21

developer   ~0022634

Please check my code corrections

abv

2012-12-21 09:22

manager   ~0022795

I have integrated corrections in branch CR21949 where:
- Default path to HTML Help Compiler on 64-bit systems is recognized
- Paths to executables can be specified by directory or file
- Messages produced by wgendoc command improved.
- Inclusion of macros DEFINE_*_ALLOC into the class documentation avoided.
- Generation of graphical class hierarchy (huge) disabled.

Please review

One problem still remains: in documentation of file Standard_TypeDef.hxx, header with path "OCCT > Module > Toolkit > Package" is repeated 10 times

ilv

2012-12-24 10:07

developer   ~0022811

Fixed tiny bugs (missing bracket and uncorrect option "basename" in the command "file")

Issue History

Date Modified Username Field Change
2011-08-02 11:19 bugmaster Category OCCT:DOC => OCCT:Documentation
2012-01-10 18:21 atp Fixed in Version EMPTY =>
2012-01-10 18:21 atp Description Updated
2012-10-26 20:02 abv Assigned To bugmaster => ilv
2012-10-26 20:02 abv Status new => assigned
2012-11-13 15:47 ilv Note Added: 0022226
2012-11-13 15:47 ilv Assigned To ilv => abv
2012-11-13 15:47 ilv Status assigned => resolved
2012-11-19 12:29 abv Assigned To abv => bugmaster
2012-11-19 12:30 abv Note Added: 0022294
2012-11-22 16:15 abv Note Added: 0022360
2012-11-22 16:15 abv Assigned To bugmaster => ilv
2012-11-22 16:15 abv Status resolved => assigned
2012-11-22 17:40 abv Note Edited: 0022360
2012-11-29 10:39 ilv Note Added: 0022430
2012-11-29 10:39 ilv Assigned To ilv => abv
2012-11-29 10:39 ilv Status assigned => resolved
2012-11-29 10:49 ilv Note Added: 0022431
2012-12-03 12:29 abv Relationship added child of 0023602
2012-12-03 17:50 abv Note Added: 0022528
2012-12-03 17:50 abv Assigned To abv => ilv
2012-12-03 17:50 abv Status resolved => assigned
2012-12-05 17:18 ilv Note Added: 0022573
2012-12-05 17:18 ilv Assigned To ilv => abv
2012-12-05 17:18 ilv Status assigned => resolved
2012-12-06 18:08 abv Note Added: 0022600
2012-12-06 18:08 abv Assigned To abv => ilv
2012-12-06 18:08 abv Status resolved => assigned
2012-12-06 18:55 abv Note Edited: 0022600
2012-12-10 10:21 ilv Note Added: 0022634
2012-12-10 10:21 ilv Assigned To ilv => abv
2012-12-10 10:21 ilv Status assigned => resolved
2012-12-21 09:22 abv Note Added: 0022795
2012-12-21 09:22 abv Assigned To abv => ilv
2012-12-21 09:30 abv Additional Information Updated
2012-12-21 14:02 abv Target Version => 6.6.0
2012-12-24 10:07 ilv Note Added: 0022811
2012-12-24 10:07 ilv Assigned To ilv => bugmaster
2012-12-24 10:07 ilv Status resolved => reviewed
2013-01-17 14:38 bugmaster Test case number => Not needed
2013-01-17 14:38 bugmaster Status reviewed => verified
2013-01-17 14:38 bugmaster Resolution open => fixed
2013-04-23 13:36 aiv Status verified => closed
2013-04-29 15:21 aiv Fixed in Version => 6.6.0