0023874: Converting OCCT MFC samples to CMake build system.
[occt.git] / dox / dev_guides / documentation / documentation.md
CommitLineData
e5bd0d98 1 Documentation System {#dev_guides__documentation}
2======================
3
4@tableofcontents
72b7576f 5
6@section OCCT_DM_SECTION_1 Introduction
7
8This document provides practical guidenes for generation and editing of OCCT user documentation.
9
10@section OCCT_DM_SECTION_2 Prerequisites
11
12<b>Tcl/Tk</b>
e5bd0d98 13Version 8.5 or 8.6: http://www.tcl.tk/software/tcltk/download.html
72b7576f 14
e5bd0d98 15<b>Doxygen</b>
16Version 1.8.4 or above: http://www.stack.nl/~dimitri/doxygen/download.html
72b7576f 17
e5bd0d98 18<b>MathJax</b> (used for rendering math formulas in browser).
19See \ref OCCT_DM_SECTION_A_9 paragraph for more detailed description.
72b7576f 20The latest version: http://www.mathjax.org/download/
21
22<b>MiKTeX</b> or equivalent tool (used for PDF document creation)
e5bd0d98 23
72b7576f 24Latest version: http://miktex.org/download
25
e5bd0d98 26**Note**: to generate pdf documentation with MiKTeX you should execute gendoc.bat within MiKTeX environment
27(run gendoc.bat in MiKTeX command promt or update PATH for MiKTeX bin folder). Also in process of pdf generation
28MiKTeX can request you to download missing packages if MiKTeX was installed with option below:
29
30@image html /dev_guides/documentation/images/documentation_image002.png
31@image latex /dev_guides/documentation/images/documentation_image002.png
32
33If this option is set to "Yes", MiKTeX will download missing packages automatically.
dba69de2 34
72b7576f 35@section OCCT_DM_SECTION_2_1 Documentation Generation
36
37Run gendoc.bat from OCCT directory to generate all articles are defined in FILES.txt:
38
39gendoc.bat options:
40
41 * -html : To generate HTML files (cannot be used with -pdf);
42 * -pdf : To generate PDF files (cannot be used with -html);
e5bd0d98 43 * -m=\<modules_list\> : Specifies list of articles to generate. If it is not specified, all files, mentioned in FILES.txt are processed;
44 * -l=\<document_name\> : Specifies the article caption for a single document;
72b7576f 45 * -h : Prints help message;
46 * -v : Specifies the Verbose mode (info on all script actions is shown).
47
48If you run the command without arguments (like example above) it will generate HTML documentation
49for all articles are defined into FILES.txt.
50
51**Note**: the generation process generates PDF files for each article,
52but in html case it generates common Html page with references to the ones.
53
54For generation of specific article you need:
55 * have it's name with relative path (from \%OCCDIR\%/dox/ to the file) contained in FILES.txt
56 (is located into \%OCCDIR\%/dox/ directory).
57
58@verbatim
59devs_guid/documentation/documentation.md
60@endverbatim
61
62where documentation .md is name of article and devs_guid/documentation/ is relative path of it
63
64 * use this name with -m option in the generation process:
65
66@verbatim
e5bd0d98 67% gendoc.bat -html -m=devs_guid/documentation/documentation.md
72b7576f 68@endverbatim
69
70Multiple files are separated with comma:
71
72@verbatim
e5bd0d98 73% gendoc.bat -html -m=MD_FILE_1,MD_FILE_2
72b7576f 74@endverbatim
75
e5bd0d98 76To sepcify a article name with -l option, use quotes to prevent incorrect interpretation of whitespaces:
72b7576f 77
78@verbatim
e5bd0d98 79% gendoc.bat -pdf -m=MD_FILE_1 -l="Label of MD_FILE_1 document"
72b7576f 80@endverbatim
81
82@section OCCT_DM_SECTION_3 Documentation Conventions
83
84This section contains information about conventions in the field of OCCT documentation file format,
85structure of documentation directories, etc.
86
87@subsection OCCT_DM_SECTION_3_1 File Format
88
79d580f2 89The format used for documentation is MarkDown with Doxygen extensions.
72b7576f 90The MarkDown files have a "*.md" extension and are based on rules desribed in
79d580f2 91\ref OCCT_DM_SECTION_A section.
72b7576f 92
93@subsection OCCT_DM_SECTION_3_2 Directory Structure
94
dba69de2 95@image html /dev_guides/documentation/images/documentation_image001.png
96@image latex /dev_guides/documentation/images/documentation_image001.png
72b7576f 97
98Every separate article has own folder if images are used in it. These images
99are stored into "images" subfolder.
100
101If you want to use the same image for several articles, you can place the one into "dox/resources" folder.
102
103**Note**: Every article can use any image that is used by others articles. To avoid incorrect image
104displaying, use relative path to the image (starting from dox folder). For instance
105@verbatim
dba69de2 106@image html /dev_guides/snv/images/snv_image001.svg
72b7576f 107@endverbatim
108
109Result of generation of the documentation is:
110
111%OCCT_DIR% / doc - a folder for generated articles;
112 * html/ - a directory for generated HTML pages;
113 * pdf/ - a directory for generated PDF files.
114
115@section OCCT_DM_SECTION_4 Adding a New Article
116
117 - Place a new article into folder that is chosen taking into account the place of the article
118at the hierarchy of the documentation. For instance the article about "using SVN working with OCCT
dba69de2 119source code" (svn.md - the file of the article) might be placed into /dox/dev_guides/ . If the article has images then you may create
72b7576f 120the own folder of the article and subfolder in it for images. For instance
dba69de2 121*/dox/dev_guides/svn/ - for svn.md file
122*/dox/dev_guides/svn/images/ - for images
72b7576f 123
124 - Update dox/FILES.txt to add relative path to svn.md. For instance
125@verbatim
dba69de2 126dev_guides/snv/svn.md
72b7576f 127@endverbatim
128
129**Note**: the place of the relative path to an article is connected with the place
130into treeview of html version.
131
132
133Note, that you should specify a file tag, not the document name.
134See <a href="#OCCT_DM_SECTION_A_1">Header section</a> for details.
135
136@section OCCT_DOC_SECTION_5 Additional Resources
137
138More information about OCCT can be found at http://www.opencascade.org
139
140The information on formula syntax can be found at:
141http://en.wikipedia.org/wiki/Help:Displaying_a_formula
142
143More information on MarkDown and Doxygen syntax can be found at:
144http://www.stack.nl/~dimitri/doxygen/manual
e5bd0d98 145
146@section OCCT_DM_SECTION_A Appendix 1: Document Syntax
147
148Each OCCT document file in *.md format has a simple structure.
149It can contain:
150
151| Content type | Obligation |
152| :---------------- | :-------------------: |
153| Header | M |
154| Footer | M |
155| Plain text | O |
156| List | O |
157| Table | O |
158| Code | O |
159| Formula | O |
160| Image | O |
161| Page numbers | M (auto generation) |
162| Table of contents | M (auto generation) |
163
164The legend:
165
166 * M is for Mandatory
167 * O is for Optional
168
169@subsection OCCT_DM_SECTION_A_1 Text Caption (a header)
170
171headings of different levels can be specified with the following code:
172
173@verbatim
174Header 1 {#header1}
175=======
176@endverbatim
177
178 to get
179
180 Header 1
181=========
182
183 and with the following code:
184
185@verbatim
186Header 2 {#header2}
187--------
188@endverbatim
189
190to get
191
192Header 2
193---------
194
195Where a word in curly braces is a MarkDown-style reference, which can be used in table of contents.
196If you would like to have the table of contents, it is recommended to use \@section,
197\@subsection and \@subsubsection pages instead of MarkDown headers as follows:
198
199@verbatim
200 @section Section_Name Section Header
201 @subsection SubSection_Name SubSection Header
202 @subsubsection SubSubSection_Name SubSubSection Header
203@endverbatim
204
205@subsection OCCT_DM_SECTION_A_2 Plain Text
206
207Plain text is a text in a notepad-like format. To insert special symbols,
208like \< , \> or \\, prepend them with \\ character: \\\<, \\\>, \\\\
209To emphasize some words, write one pair of asterisks ( * ) or underscores ( _ ) across the word
210to make it *italic* and two pairs of these symbols to make a word **Bold**.
211
212@subsection OCCT_DM_SECTION_A_3 Lists
213
214To create a bulleted list, start each line with a hyphen or an asterisk,
215followed by a space. List items can be nested. This code:
216
217@verbatim
79d580f2 218* Bullet 1
219* Bullet 2
220 - Bullet 2a
221 - Bullet 2b
222* Bullet 3
e5bd0d98 223@endverbatim
224
79d580f2 225produces this list:
e5bd0d98 226
79d580f2 227* Bullet 1
228* Bullet 2
229 * Bullet 2a
230 * Bullet 2b
231* Bullet 3
e5bd0d98 232
79d580f2 233To create a numbered list, start each line with number and a period,
234then a space. Numbered lists can also be nested. Thus this code
e5bd0d98 235
236@verbatim
79d580f2 2371. List item 1
238 1. Sub-item 1
239 2. Sub-item 2
2402. List item 2
2413. List item 3
e5bd0d98 242@endverbatim
243
79d580f2 244produces this list:
e5bd0d98 245
79d580f2 2461. List item 1
247 1. Sub-item 1
248 2. Sub-item 2
2492. List item 2
2503. List item 3
e5bd0d98 251
79d580f2 252Each list item can contain several paragraphs of text; these paragraphs must
253have the same indentation as text after bullet or number in the numbered list
254item (otherwise numbering will be broken).
255
256Code blocks can be inserted as paragraphs with additional indentation
257(4 spaces more). Note that fenced code blocks do not work within numbered lists
258and their use may cause numeration to be reset.
259
260
261Example of complex nested list:
262
263@verbatim
2641. ListItem_1
265
266 Additional paragraph
267
268 code fragment
269
270 One more paragraph
271
272 1. Sub-item 1
273
274 code fragment for sub-item 1
275
276 2. Sub-item 2
277
278 Paragraph for sub-item 2
279
280 Yet one more paragraph for list item 1
281
2822. ListItem_2
283@endverbatim
284
2851. List item 1
286
287 Additional paragraph
288
289 code fragment
290
291 One more paragraph
292
293 1. Sub-item 1
294
295 code fragment for sub-item 1
296
297 2. Sub-item 2
298
299 Paragraph for sub-item 2
300
301 Yet one more paragraph for list item 1
302
3032. List item 2
304
305Note that numbers of paragraphs are regenerated so they do not necessarily
306follow numbering of source items.
e5bd0d98 307
308@subsection OCCT_DM_SECTION_A_4 Tables
309
310A table consists of a header line, a separator line, and at least one row line.
311Table columns are separated by the pipe (|) character. The following example:
312
313@verbatim
314First Header | Second Header
315------------- | -------------
316Content Cell | Content Cell
317Content Cell | Content Cell
318@endverbatim
319
320 will produce the following table:
321
322First Header | Second Header
323------------ | -------------
324Content Cell | Content Cell
325Content Cell | Content Cell
326
327Column alignment can be controlled via one or two colons at the header separator line:
328
329@verbatim
330| Right | Center | Left |
331| ----: | :----: | :---- |
332| 10 | 10 | 10 |
333| 1000 | 1000 | 1000 |
334@endverbatim
335
336which will looks as follows:
337
338| Right | Center | Left |
339| ----: | :----: | :---- |
340| 10 | 10 | 10 |
341| 1000 | 1000 | 1000 |
342
79d580f2 343Note that each table raw should be contained in one line of text; complex
344tables can be created using HTML tags.
345
e5bd0d98 346@subsection OCCT_DM_SECTION_A_5 Code Blocks
347
348It is recommended to indent a code lines with 4 spaces.
349A fenced code block does not require indentation, and is defined by a pair of "fence lines".
350Such line consists of 3 or more tilde (~) characters on a line.
351The end of the block should have the same number of tildes. Here is an example:
352
353~~~~~~~~~~~~~~~~~~~~~~~
354 a one-line code block
355~~~~~~~~~~~~~~~~~~~~~~~
356
357By default the output is the same as for a normal code block.
358To highlight the code, the developer has to indicate the typical file extension,
359which corresponds to the programming language, after the opening fence.
360For highlighting according to the C++ language, for instance, write the following code (the curly braces and dot are optional):
361
362@verbatim
363~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~{.cpp}
364 int func(int a,int b) { return a*b; }
365~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
366@endverbatim
367
368which will produce:
369~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~{.cpp}
370 int func(int a,int b) { return a*b; }
371~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
372
373Verbatim content can be written by using framing \@verbatim \@endverbatim . For instance
374
375@verbatim
376 verbatim text
377@endverbatim
378
379@subsection OCCT_DM_SECTION_A_6 References
380
381To insert a reference to a website, it is proposed to write a URL. For example: http://en.wikipedia.org
382To insert a reference to another part of the same document, the developer can write:
383
384@verbatim
385 @htmlonly
386 <a href="#OCCT_DOC_SECTION_5">Doxygen Configuration file</a>
387 @endhtmlonly
388@endverbatim
389
390to get a link to paragraph : @htmlonly <a href="#OCCT_DOC_SECTION_5">Doxygen configuration</a> @endhtmlonly
391
392@subsection OCCT_DM_SECTION_A_7 Images
393
394To insert image into document the developer can write the following code(in Doxygen-style):
395@verbatim
396![alt-caption](relative/path/to/image/image001.svg "Image Caption")
397@endverbatim
398
399This code tells Doxygen to insert a picture right in the place this code was written. Like this:
400@verbatim
401![](/resources/occ_logo.png "OCCT logo")
402@endverbatim
403
404![](/resources/occ_logo.png "OCCT logo")
405
406@subsection OCCT_DM_SECTION_A_8 Table Of Contents
407
408To get the table of contents at the beginning of the document, write \@tableofcontents tag.
409But it is not needed now because TreeView option for HTML is used.
410The TOC in the PDF document will be generated automatically.
411
412@subsection OCCT_DM_SECTION_A_9 Formulas
413
414Formulas within documents will be generated using MathJax tool.
415
416A developer has to specify these parameters in Doxyfile to enable support of MathJax in Doxygen:
417
418 USE_MATHJAX = YES
419 MATHJAX_FORMAT = HTML-CSS
420 MATHJAX_RELPATH = http://cdn.mathjax.org/mathjax/latest
421 MATHJAX_EXTENSIONS = TeX/AMSmath TeX/AMSsymbols
422
423To use MathJax tool with the HTML page, it's \<head\> block has to contain
424
425~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~{.html}
426 <script type="text/x-mathjax-config">
427 MathJax.Hub.Config({
428 tex2jax: {inlineMath: [["$","$"],["\\(","\\)"]]},
429 displayAlign: "left"
430 });
431 </script>
432
433 <script type="text/javascript"
434 src="http://cdn.mathjax.org/mathjax/latest/MathJax.js?config=TeX-AMS-MML_HTMLorMML">
435 </script>
436~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
437
438First script configures MathJax to understand separator types and to left allign formulas.
439The second script inserts reference to MathJax tool.
440This tool will always be used when the HTML output will be shown.
441
442Equations can be written by several ways:
443
4441.Unnumbered displayed formulas that are centered on a separate line.
445These formulas should be put between \@f\[ and \@f\] tags. An example:
446
447@verbatim
448@f$[
449 |I_2|=\left| \int_{0}^T \psi(t)
450 \left\{
451 u(a,t)-
452 \int_{\gamma(t)}^a
453 \frac{d\theta}{k(\theta,t)}
454 \int_{a}^\theta c(\xi)u_t(\xi,t)\,d\xi
455 \right\} dt
456 \right|
457@f$]
458@endverbatim
459
460gives the following result:
461
462 @f$
463 |I_2|=\left| \int_{0}^T \psi(t)
464 \left\{
465 u(a,t)-
466 \int_{\gamma(t)}^a
467 \frac{d\theta}{k(\theta,t)}
468 \int_{a}^\theta c(\xi)u_t(\xi,t)\,d\xi
469 \right\} dt
470 \right|
471 @f$
472
4732.Formulas can also be put between @verbatim \begin{align} @endverbatim and @verbatim \end{align} @endverbatim tags. An example:
474
475@verbatim
476 \begin{align}
477 \dot{x} & = \sigma(y-x) \\
478 \dot{y} & = \rho x - y - xz \\
479 \dot{z} & = -\beta z + xy
480 \end{align}
481@endverbatim
482
483 gives the following result:
484@latexonly
485 \begin{align}
486 \dot{x} & = \sigma(y-x) \\
487 \dot{y} & = \rho x - y - xz \\
488 \dot{z} & = -\beta z + xy
489 \end{align}
490@endlatexonly
491
492@htmlonly
493 \begin{align}
494 \dot{x} & = \sigma(y-x) \\
495 \dot{y} & = \rho x - y - xz \\
496 \dot{z} & = -\beta z + xy
497 \end{align}
498@endhtmlonly
499
5003.Inline formulas can be specified using this syntax:
501
502@verbatim
503 @f$ \sqrt{3x-1}+(1+x)^2 @f$
504@endverbatim
505
506 that leads to the following result: @f$ \sqrt{3x-1}+(1+x)^2 @f$
507