# Documentation System

## Introduction

This document provides practical guidenes for generation and editing of OCCT user documentation.

## Prerequisites

MiKTeX or equivalent tool (used for PDF document creation)

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 MiKTeX can request you to download missing packages if MiKTeX was installed with option below:

If this option is set to "Yes", MiKTeX will download missing packages automatically.

## Documentation Generation

Run gendoc.bat from OCCT directory to generate all articles are defined in FILES.txt:

gendoc.bat options:

• -html : To generate HTML files (cannot be used with -pdf);
• -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;
• -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.

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).
devs_guid/documentation/documentation.md


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:
% gendoc.bat -html -m=devs_guid/documentation/documentation.md


Multiple files are separated with comma:

% 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:

% gendoc.bat -pdf -m=MD_FILE_1 -l="Label of MD_FILE_1 document"


## Documentation Conventions

This section contains information about conventions in the field of OCCT documentation file format, structure of documentation directories, etc.

### File Format

The format used for documentation is MarkDown with Doxygen extensions. The MarkDown files have a "*.md" extension and are based on rules desribed in Appendix 1: Document Syntax section.

### Directory Structure

Every separate article has own folder if images are used in it. These images are stored into "images" subfolder.

If you want to use the same image for several articles, you can place the one into "dox/resources" folder.

Note: Every article can use any image that is used by others articles. To avoid incorrect image displaying, use relative path to the image (starting from dox folder). For instance

@image html /dev_guides/snv/images/snv_image001.svg


Result of generation of the documentation is:

OCCT_DIR% / doc - a folder for generated articles;

• html/ - a directory for generated HTML pages;
• pdf/ - a directory for generated PDF files.

• Place a new article into folder that is chosen taking into account the place of the article at the hierarchy of the documentation. For instance the article about "using SVN working with OCCT source code" (svn.md - the file of the article) might be placed into /dox/dev_guides/ . If the article has images then you may create the own folder of the article and subfolder in it for images. For instance */dox/dev_guides/svn/ - for svn.md file */dox/dev_guides/svn/images/ - for images
• Update dox/FILES.txt to add relative path to svn.md. For instance
dev_guides/snv/svn.md


Note: the place of the relative path to an article is connected with the place into treeview of html version.

Note, that you should specify a file tag, not the document name. See Header section for details.

The information on formula syntax can be found at: http://en.wikipedia.org/wiki/Help:Displaying_a_formula

More information on MarkDown and Doxygen syntax can be found at: http://www.stack.nl/~dimitri/doxygen/manual

## Appendix 1: Document Syntax

Each OCCT document file in *.md format has a simple structure. It can contain:

Content type Obligation
Footer M
Plain text O
List O
Table O
Code O
Formula O
Image O
Page numbers M (auto generation)

The legend:

• M is for Mandatory
• O is for Optional

headings of different levels can be specified with the following code:

Header 1  {#header1}
=======


to get

and with the following code:

Header 2 {#header2}
--------


to get

  @section Section_Name Section Header


### Plain Text

Plain text is a text in a notepad-like format. To insert special symbols, like < , > or \, prepend them with \ character: \<, \>, \\ To emphasize some words, write one pair of asterisks ( * ) or underscores ( _ ) across the word to make it italic and two pairs of these symbols to make a word Bold.

### Lists

To create a bulleted list, start each line with a hyphen or an asterisk, followed by a space. List items can be nested. This code:

* Bullet 1
* Bullet 2
- Bullet 2a
- Bullet 2b
* Bullet 3


produces this list:

• Bullet 1
• Bullet 2
• Bullet 2a
• Bullet 2b
• Bullet 3

To create a numbered list, start each line with number and a period, then a space. Numbered lists can also be nested. Thus this code

1. List item 1
1. Sub-item 1
2. Sub-item 2
2. List item 2
3. List item 3


produces this list:

1. List item 1
1. Sub-item 1
2. Sub-item 2
2. List item 2
3. List item 3

Each list item can contain several paragraphs of text; these paragraphs must have the same indentation as text after bullet or number in the numbered list item (otherwise numbering will be broken).

Code blocks can be inserted as paragraphs with additional indentation (4 spaces more). Note that fenced code blocks do not work within numbered lists and their use may cause numeration to be reset.

Example of complex nested list:

1. ListItem_1

code fragment

One more paragraph

1. Sub-item 1

code fragment for sub-item 1

2. Sub-item 2

Paragraph for sub-item 2

Yet one more paragraph for list item 1

2. ListItem_2

1. List item 1

code fragment


One more paragraph

1. Sub-item 1
code fragment for sub-item 1

2. Sub-item 2

Paragraph for sub-item 2

Yet one more paragraph for list item 1

2. List item 2

Note that numbers of paragraphs are regenerated so they do not necessarily follow numbering of source items.

### Tables

A table consists of a header line, a separator line, and at least one row line. Table columns are separated by the pipe (|) character. The following example:

First Header  | Second Header
------------- | -------------
Content Cell  | Content Cell
Content Cell  | Content Cell


will produce the following table:

Content Cell Content Cell
Content Cell Content Cell

Column alignment can be controlled via one or two colons at the header separator line:

| Right | Center | Left  |
| ----: | :----: | :---- |
| 10    | 10     | 10    |
| 1000  | 1000   | 1000  |


which will looks as follows:

Right Center Left
10 10 10
1000 1000 1000

Note that each table raw should be contained in one line of text; complex tables can be created using HTML tags.

### Code Blocks

It is recommended to indent a code lines with 4 spaces. A fenced code block does not require indentation, and is defined by a pair of "fence lines". Such line consists of 3 or more tilde (~) characters on a line. The end of the block should have the same number of tildes. Here is an example:

a one-line code block

By default the output is the same as for a normal code block. To highlight the code, the developer has to indicate the typical file extension, which corresponds to the programming language, after the opening fence. For highlighting according to the C++ language, for instance, write the following code (the curly braces and dot are optional):

~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~{.cpp}
int func(int a,int b) { return a*b; }
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~


which will produce:

int func(int a,int b) { return a*b; }

Verbatim content can be written by using framing @verbatim @endverbatim . For instance

verbatim text


### References

To insert a reference to a website, it is proposed to write a URL. For example: http://en.wikipedia.org To insert a reference to another part of the same document, the developer can write:

  @htmlonly
<a href="#OCCT_DOC_SECTION_5">Doxygen Configuration file</a>
@endhtmlonly


to get a link to paragraph : Doxygen configuration

### Images

To insert image into document the developer can write the following code(in Doxygen-style):

For HTML document:

  @image html /relative/path/to/image/image001.png "Image caption"


For latex document:

  @image latex /relative/path/to/image/image001.png "Image caption"


Note: When markdown document is used to generate html document the latex insertion is ignored (and vice versa) due to this fact you can use image insertions in the pair, like example below:

  @image html /relative/path/to/image/image001.png "Image caption"
@image latex /relative/path/to/image/image001.png "Image caption"


The code below tells Doxygen to insert a picture right in the place this code was written:

  @image html /resources/occ_logo.png "OCCT logo"
@image latex /resources/occ_logo.png "OCCT logo"

OCCT logo

To get the table of contents at the beginning of the document, write @tableofcontents tag. But it is not needed now because TreeView option for HTML is used. The TOC in the PDF document will be generated automatically.

### 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

<script type="text/x-mathjax-config">
MathJax.Hub.Config({
tex2jax: {inlineMath: [["$","$"],["\$$","\$$"]]},
displayAlign: "left"
});
</script>
<script type="text/javascript"
src="https://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:

1.Unnumbered displayed formulas that are centered on a separate line. These formulas should be put between @f[ and @f] tags. An example:

@f[
|I_2|=\left| \int_{0}^T \psi(t)
\left\{
u(a,t)-
\int_{\gamma(t)}^a
\frac{d\theta}{k(\theta,t)}
\int_{a}^\theta c(\xi)u_t(\xi,t)\,d\xi
\right\} dt
\right|
@f]


gives the following result:

$$|I_2|=\left| \int_{0}^T \psi(t) \left\{ u(a,t)- \int_{\gamma(t)}^a \frac{d\theta}{k(\theta,t)} \int_{a}^\theta c(\xi)u_t(\xi,t)\,d\xi \right\} dt \right|$$

2.Formulas can also be put between

\begin{align}

and

\end{align}

tags. An example:

  \begin{align}
\dot{x} & = \sigma(y-x) \\
\dot{y} & = \rho x - y - xz \\
\dot{z} & = -\beta z + xy
\end{align}


gives the following result: \begin{align} \dot{x} & = \sigma(y-x) \\ \dot{y} & = \rho x - y - xz \\ \dot{z} & = -\beta z + xy \end{align}

3.Inline formulas can be specified using this syntax:

  @f$\sqrt{3x-1}+(1+x)^2 @f$


that leads to the following result: $$\sqrt{3x-1}+(1+x)^2$$