OCCT documentation project

Publication of the documentation sources.
Project leader: Yury Solomatin (ysn)
Forum: Documentation
Mantis issue: #23962
Status: Completed

Overview

The evolution of the Open CASCADE Technology also requires the evolution of reference and user documentation, including class references, tutorials and user guides. Historically the Open CASCADE Technology and its documentation have been developed separately, so there were many difficulties with keeping the project and especially the user documentation up-to-date.

The main goal of this project was to put OCCT documentation in open source and integrate it with OCCT sources and development environment. This should help keeping the documentation up-to-date with changes in OCCT sources, and facilitate development of the new documentation.

Agenda

The following actions were planned:

• Choose the tools and develop the environment for documentation;
• Convert the Overview documentation from Robohelp to Doxygen format;
• Convert the User Guides from Word to Doxygen format;
• Include the documentation sources in Git repository;
• Provide the tools to build the documentation from sources;
• Create a single documentation package integrating Overview, User Guides, and Reference Manual;
• Provide on-line access to the documentation from the Web site.

Progress

The project was started in May 2013 from the analysis of the available tools and approaches we can use for creation of documentation. Naturally Doxygen has been the first tool taken into consideration, as it is already used for generation of the reference manual, and we are confident that it is the right tool to be used.

The new OCCT documentation gets advantage of the features added recently in Doxygen:

• Use Markdown format for writing textual documents;
• Use MathJAX for rendering of math expressions.

HTML is considered as the main output format for documentation. Overview documentation can be generated also in CHM format. User Guides can be output in PDF format, with help of MikTeX (or other TeX/LaTeX implementation).

All the planned tasks were completed by December 2013, and the new documentation is included in OCCT since version 6.7.0.

HTML Documentation for current development version of OCCT is available online, see http://dev.opencascade.org/doc. PDF and CHM documentation is included in release packages.

Further development

Further development of documentation is part of the overall OCCT development.

Version 6.7.1 will contain updated procedure for generation of documentation, not requiring WOK for generation of Reference Manual, and supporting SVG images.

Version 6.8.0 will include new document describing Boolean Operations algorithm, and updates of existing User and Developer Guides.

How to help

Everyone is welcome to share ideas, comments, proposals regarding the new documentation system using the forum or Mantis.

Volunteers are invited to proofread the documentation and improve it -- either directly by contributing modifications, or indirectly by commenting.

If you have specific requirements or urgent needs, you can also boost the project through ordering OCC support services