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