0023962: Moving OCCT documentation to sources

[occt.git] / dox / dev_guides / documentation / documentation.md

 Documentation  {#dev_guides__documentation}
=================

@section  OCCT_DM_SECTION_1 Introduction

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

@section  OCCT_DM_SECTION_2 Prerequisites

<b>Tcl/Tk</b>
The lates version: http://www.tcl.tk/software/tcltk/download.html

<b>Doxygen</b> ( >= 1.8.4 ) 
The latest version: http://www.stack.nl/~dimitri/doxygen/download.html

<b>MathJax</b> (used for rendering math formulas in browser). Download it for local installation or use the MathJax Content Delivery Network.  \(read 
@htmlonly <a href="#OCCT_DM_SECTION_A_9">Formulas</a> @endhtmlonly 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

@section OCCT_DM_SECTION_2_1 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).

@verbatim
devs_guid/documentation/documentation.md
@endverbatim

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:

@verbatim
% gen.bat -html -m=devs_guid/documentation/documentation.md
@endverbatim

Multiple files are separated with comma:

@verbatim
% gen.bat -html -m=MD_FILE_1,MD_FILE_2
@endverbatim

To sepcify a article name with -l option, use tcl list to prevent whitespaces incorrect interpretation:

@verbatim
% gen.bat -pdf -m=MD_FILE_1 -l=[list MD File 1 Label]
@endverbatim

@section  OCCT_DM_SECTION_3 Documentation Conventions

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

@subsection  OCCT_DM_SECTION_3_1 File Format

It is proposed to use MarkDown file format for easy maintainance of generic text documents. 
The MarkDown files have a "*.md" extension and are based on rules desribed in 
@htmlonly <a href="#OCCT_DM_SECTION_A">Document Syntax</a> @endhtmlonly section.

@subsection  OCCT_DM_SECTION_3_2 Directory Structure

![](/devs_guide/documentation/images/documentation_image001.png)

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
@verbatim
![](/devs_guide/snv/images/snv_image001.svg)
@endverbatim

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.

@section  OCCT_DM_SECTION_4 Adding a New Article

 - 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/devs_guide/ . If the article has images then you may create
the own folder of the article and subfolder in it for images. For instance
*/dox/devs_guide/svn/ - for svn.md file
*/dox/devs_guide/svn/images/ - for images

 - Update dox/FILES.txt to add relative path to svn.md. For instance
@verbatim
devs_guide/snv/svn.md
@endverbatim

**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 <a href="#OCCT_DM_SECTION_A_1">Header section</a> for details.

@section  OCCT_DOC_SECTION_5 Additional Resources

More information about OCCT can be found at http://www.opencascade.org

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


@section  OCCT_DM_SECTION_A Appendix 1: Document Syntax

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

| Content type      | Obligation            |
| :---------------- | :-------------------: |
| Header            | M                     |
| Footer            | M                     |
| Plain text        | O                     |
| List              | O                     |
| Table             | O                     |
| Code              | O                     |
| Formula           | O                     |
| Image             | O                     |
| Page numbers      | M (auto generation)   |
| Table of contents | M (auto generation)   |

The legend:

  * M is for Mandatory
  * O is for Optional

@subsection  OCCT_DM_SECTION_A_1 Text Caption (a header)

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

@verbatim
Header 1  {#header1}
=======
@endverbatim

  to get

 Header 1
=========

  and with the following code:

@verbatim
Header 2 {#header2}
--------
@endverbatim

to get 

Header 2
---------

Where a word in curly braces is a MarkDown-style reference, which can be used in table of contents.
If you would like to have the table of contents, it is recommended to use \@section, 
\@subsection and \@subsubsection pages instead of MarkDown headers as follows:

@verbatim
  @section Section_Name Section Header
  @subsection SubSection_Name SubSection Header
  @subsubsection SubSubSection_Name SubSubSection Header
@endverbatim

@subsection OCCT_DM_SECTION_A_2 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**.

@subsection OCCT_DM_SECTION_A_3 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:

@verbatim
  * Bullet 1
  * Bullet 2
    * Bullet 2a
    * Bullet 2b
  * Bullet 3
@endverbatim

  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. Thus this code 

@verbatim
  1. ListItem_1
  2. ListItem_2
  3. ListItem_3
@endverbatim

  produces this list:

  1. ListItem_1
  2. ListItem_2
  3. ListItem_3

It is recommended to indent lists with 2 spaces.

@subsection  OCCT_DM_SECTION_A_4 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: 

@verbatim
First Header  | Second Header
------------- | -------------
Content Cell  | Content Cell 
Content Cell  | Content Cell 
@endverbatim

  will produce the following table:

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

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

@verbatim
| Right | Center | Left  |
| ----: | :----: | :---- |
| 10    | 10     | 10    |
| 1000  | 1000   | 1000  |
@endverbatim

which will looks as follows:

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

@subsection  OCCT_DM_SECTION_A_5 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): 

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

which will produce:
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~{.cpp} 
    int func(int a,int b) { return a*b; }
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

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

@verbatim
  verbatim text
@endverbatim

@subsection  OCCT_DM_SECTION_A_6 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:

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

to get a link to paragraph : @htmlonly <a href="#OCCT_DOC_SECTION_5">Doxygen configuration</a> @endhtmlonly 

@subsection  OCCT_DM_SECTION_A_7 Images

To insert image into document the developer can write the following code(in Doxygen-style):
@verbatim
![alt-caption](relative/path/to/image/image001.svg "Image Caption")
@endverbatim

This code tells Doxygen to insert a picture right in the place this code was written. Like this:
@verbatim
![](/resources/occt_logo.png "OCCT logo")
@endverbatim

![](/resources/occt_logo.png "OCCT logo")
 
@subsection  OCCT_DM_SECTION_A_8 Table Of Contents

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.

@subsection  OCCT_DM_SECTION_A_9 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 

~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~{.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:

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

@verbatim
@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$]
@endverbatim

gives the following result:

   @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$
   
2.Formulas can also be put between @verbatim \begin{align} @endverbatim and @verbatim \end{align} @endverbatim tags. An example: 

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

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

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

3.Inline formulas can be specified using this syntax:

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

  that leads to the following result: @f$ \sqrt{3x-1}+(1+x)^2 @f$
  
@section  OCCT_DM_SECTION_B Appendix 2: Doxygen Configuration

@subsection OCCT_DM_SECTION_B_1 Doxygen Configuration File

To generate documentation from "source" *.md files a developer can use file OCCT.doxyfile, 
which is located in /docs directory of OCCT (more information can be found at @htmlonly 
<a href="#OCCT_DM_SECTION_X_X_X">Directory Structure</a> @endhtmlonly paragraph)
or create his own configuration file, called "Doxyfile". The configuration file may look as follows: 

@verbatim
  DOXYFILE_ENCODING      = UTF-8
  PROJECT_NAME           = "OCCT User's Guides"
  PROJECT_NUMBER         = 1.0.1
  PROJECT_LOGO           = "D:/OS/OCCT/docs/OCCT_logo.png"
  OUTPUT_LANGUAGE        = English
  TAB_SIZE               = 4
  MARKDOWN_SUPPORT       = YES
  AUTOLINK_SUPPORT       = NO
  SHOW_FILES             = NO
  WARNINGS               = YES
  WARN_IF_UNDOCUMENTED   = YES
  WARN_IF_DOC_ERROR      = YES
  WARN_NO_PARAMDOC       = NO
  WARN_FORMAT            = "$file:$line: $text"
  INPUT                  = "D:/OS/OCCT/docs/"
  INPUT_ENCODING         = UTF-8
  FILE_PATTERNS          = *.md
  RECURSIVE              = YES
  IMAGE_PATH             = tmp
  GENERATE_HTML          = YES
  SEARCHENGINE           = NO
  HTML_OUTPUT            = html
  HTML_FILE_EXTENSION    = .html
  HTML_HEADER            = "static/header.html"
  HTML_FOOTER            = "static/footer.html"
  HTML_STYLESHEET        = "static/general.css"
  HTML_EXTRA_STYLESHEET  = "static/styles.css"
  HTML_COLORSTYLE_HUE    = 220
  HTML_COLORSTYLE_SAT    = 100
  HTML_COLORSTYLE_GAMMA  = 80
  HTML_TIMESTAMP         = YES
  HTML_DYNAMIC_SECTIONS  = NO
  HTML_INDEX_NUM_ENTRIES = 100
  GENERATE_LATEX         = YES
  GENERATE_RTF           = YES
@endverbatim

@subsection OCCT_DM_SECTION_B_2 Doxygen Output Customization

The customization of the output files, produced by Doxygen, can be made by using different Doxyfile parameters,
like HTML_COLORSTYLE_SAT, which specifies one of HSV color component of HTML page header, and also by using DoxygenLayout xml file.
A developer can use default file from /docs directory or generate his own with doxygen -l command. It may looks as follows:

~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~{.xml}
<doxygenlayout version="1.0">
  <!-- Generated by doxygen 1.8.3.1 -->
  <!-- Navigation index tabs for HTML output -->
  <navindex>
    <tab type="mainpage" visible="yes" title="Introduction"/>
    <tab type="pages" visible="yes" title="Documents" intro=
    "This section contains links to all OCCT documents that are available at the moment"/>
    <tab type="modules" visible="no" title="" intro=""/>
    <tab type="namespaces" visible="no" title="">
      <tab type="namespacelist" visible="no" title="" intro=""/>
      <tab type="namespacemembers" visible="no" title="" intro=""/>
    </tab>
    <tab type="classes" visible="no" title="">
      <tab type="classlist" visible="no" title="" intro=""/>
      <tab type="classindex" visible="$ALPHABETICAL_INDEX" title=""/> 
      <tab type="hierarchy" visible="no" title="" intro=""/>
      <tab type="classmembers" visible="no" title="" intro=""/>
    </tab>
    <tab type="files" visible="yes" title="Files">
      <tab type="filelist" visible="yes" title="" intro=""/>
      <tab type="globals" visible="yes" title="" intro=""/>
    </tab>
    <tab type="examples" visible="no" title="" intro=""/>  
  </navindex>
    ...
</doxygenlayout>
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

The tag \<tab\> specifies tabs which appear at the head of each html page. For the OCCT user documentation
 "mainpage" and "pages" tabs are usually needed and their visible parameter should always be "yes". 
The visibility of other tabs should be set to "no".

Developers can find more information about Doxygen configuration in the help file 
or at http://www.stack.nl/~dimitri/doxygen/manual/

@subsection OCCT_DM_SECTION_B_3 Doxywizard Usage

The easiest way of applying and modification of Doxyfile is to use a Doxywizard application, 
which is usually a part of the Doxygen tool. To apply a configuration file, the developer should 
select "Open..." item of the File menu or press Ctrl + O. Modification of Doxyfile can be made
using "Wizard" or "Expert" tabs of Doxywizard application. 

Developers can find more information about Doxywizard usage in the help file or at 
http://www.stack.nl/~dimitri/doxygen/manual/doxywizard_usage.html.