0028654: Existed tool (gendoc) for generation documentation does not take into accoun...
[occt.git] / dox / dev_guides / documentation / documentation.md
1  Documentation System {#occt_dev_guides__documentation}
2 ======================
3
4 @tableofcontents
5
6 @section  OCCT_DM_SECTION_1 Introduction
7
8 This document provides practical guidelines for generation and editing of OCCT user documentation.
9
10 @section  OCCT_DM_SECTION_2 Prerequisites
11
12 You need to have the following software installed to generate the documentation.
13
14 **Tcl/Tk**
15 Version 8.5 or 8.6: http://www.tcl.tk/software/tcltk/download.html
16
17 **Doxygen**
18 Version 1.8.4 or above: http://www.stack.nl/~dimitri/doxygen/download.html
19
20 **Dot**
21 Part of Graphviz software, used by Doxygen for generation of class diagrams in Reference Manual: http://www.graphviz.org/Download..php
22
23 **MiKTeX** or other package providing **pdflatex** command (only needed for generation of PDF documents): http://miktex.org/download
24
25 **Inkscape** (only needed for generation of PDF documents containing SVG images): http://www.inkscape.org/download
26
27 When generating PDF documentation, **pdflatex** and **inkscape** executables should be accessible by PATH variable.
28 You can use *custom.bat* file to add necessary paths to the *PATH* variable. 
29
30 Note that in the process of PDF generation MiKTeX may need some packages not installed by default.
31 We recommend setting option "Install missing packages on-the-fly" to "Ask me first" (default) during MiKTeX installation:
32
33 @figure{/dev_guides/documentation/images/documentation_miktex.png,"",320}
34
35 On the first run of **pdflatex** it will open a dialog window prompting for installation of missing packages.
36 Follow the instructions to proceed (define proxy settings if needed, select a mirror site to download from, etc.).
37
38 **MathJax** is used for rendering math formulas in browser (HTML and CHM outputs): http://www.mathjax.org.
39
40 By default MathJAX scripts and fonts work on-line and no installation of MathJAX is necessary if Internet is accessible.
41 If you need to use OCCT documentation while off-line, you can install a local copy of MatJAX, see https://docs.mathjax.org/en/v2.6-latest/start.html#installing-your-own-copy-of-mathjax.
42 See \ref OCCT_DM_SECTION_A_9 for more details on inserting mathematical expressions. 
43
44 @section OCCT_DM_SECTION_2_1 Documentation Generation
45
46 Run command *gendoc* from command prompt (with OCCT directory as current one) to generate OCCT documentation.
47 The synopsis is:
48
49     gendoc \[-h\] {-refman|-overview} \[-html|-pdf|-chm\] \[-m=<list of modules>|-ug=<list of docs>\] \[-v\] \[-s=<search_mode>\] \[-mathjax=<path>\]
50         
51 Here the options are:
52
53 * Choice of documentation to be generated:
54   * <i>-overview</i>: To generate Overview and User Guides (cannot be used with -refman)
55   * <i>-refman</i>: To generate class Reference Manual (cannot be used with -overview)
56
57 * Choice of output format:
58   * <i>-html</i>: To generate HTML files (default, cannot be used with -pdf or -chm)
59   * <i>-pdf</i>: To generate PDF files (cannot be used with -refman, -html, or -chm)
60   * <i>-chm</i>: To generate CHM files (cannot be used with -html or -pdf)
61
62 * Additional options:
63   * <i>-m=\<modules_list\></i>: List of OCCT modules (separated with comma), for generation of Reference Manual
64   * <i>-ug=\<docs_list\></i>: List of MarkDown documents (separated with comma), to use for generation of Overview / User Guides
65   * <i>-mathjax=\<path\></i>: To use local or alternative copy of MathJax
66   * <i>-s=\<search_mode\></i>: Specifies the Search mode of HTML documents; can be: none | local | server | external
67   * <i>-h</i>: Prints this help message
68   * <i>-v</i>: Enables more verbose output
69
70 **Note**
71
72 * In case of PDF output the utility generates a separate PDF file for each document;
73 * In case of HTML output the utility generates a common Table of contents containing references to all documents.
74 * In case of CHM output single CHM file is generated
75
76 **Examples**
77
78 To generate the output for a specific document specify the path to the corresponding MarkDown file (paths relative to *dox* sub-folder can be given), for instance:
79
80 ~~~~
81     > gendoc -overview -ug=dev_guides/documentation/documentation.md
82 ~~~~
83
84 To generate Reference Manual for the whole Open CASCADE Technology library, run: 
85 ~~~~
86     > gendoc -refman
87 ~~~~
88
89 To generate Reference Manual for Foundation Classes and Modeling Data modules only, with search option, run:
90 ~~~~
91     > gendoc -refman -m=FoundationClasses,ModelingData,ModelingAlgorithms -s=local
92 ~~~~
93
94 @section  OCCT_DM_SECTION_3 Documentation Conventions
95
96 This section contains information about file format conventions, directories structure, etc.
97
98 @subsection  OCCT_DM_SECTION_3_1 File Format
99
100 The format used for documentation is MarkDown with Doxygen extensions. 
101 The MarkDown files have a <i>*.md</i> extension and are based on rules described in \ref OCCT_DM_SECTION_A section.
102
103 @subsection  OCCT_DM_SECTION_3_2 Directory Structure
104
105 @figure{/dev_guides/documentation/images/documentation_folders.png,"",160}
106
107 Each document has its own folder if there are any images used in it. These images are stored in *images* subfolder.
108
109 If you want to use the same image for several documents, you can place it in *dox/resources* folder.
110
111 **Note**: To avoid incorrect image display, use a relative path to the image (starting from *dox* folder). For instance:
112
113
114 @verbatim
115 @figure{/dev_guides/documentation/images/documentation_test_image.svg,"",420}
116 @endverbatim
117
118
119 The documentation is generated in subfolder *doc* :
120 * *html* -- a directory for generated HTML pages;
121 * *pdf* -- a directory for generated PDF files.
122
123 @section  OCCT_DM_SECTION_4 Adding a New Document
124
125 Place a new document in the folder taking into account its logical position in the documentation hierarchy. For instance, the document *svn.md* about the use of SVN to work with OCCT source code can be placed into <i>/dox/dev_guides/</i>. 
126
127 If there are images in the document, it should be placed in its own folder containing a subfolder for images. For instance:
128 * <i> /dox/dev_guides/svn/ </i> -- for *svn.md* file;
129 * <i> /dox/dev_guides/svn/images/ </i> -- for images.
130
131 Add a relative path to *svn.md* in file <i>dox/FILES.txt</i>. For instance
132
133 @verbatim
134 dev_guides/svn/svn.md
135 @endverbatim
136
137 **Note** that the order of paths to documents in *FILES.txt* is reproduced in the Table of Contents in the HTML output. Please, place them logically.
138
139 **Note** that you should specify a file tag, not the document name. See @ref OCCT_DM_SECTION_A_1 "Header and hierarchic document structure" section for details.
140
141 @section  OCCT_DOC_SECTION_5 Additional Resources
142
143 More information about OCCT can be found at http://www.opencascade.com and <br> http://dev.opencascade.org sites. 
144
145
146 The information on formula syntax can be found at: <br>
147 http://en.wikipedia.org/wiki/Help:Displaying_a_formula
148
149 More information on MarkDown and Doxygen syntax can be found at: <br>
150 http://www.stack.nl/~dimitri/doxygen/manual
151
152 @section  OCCT_DM_SECTION_A Appendix 1: Document Syntax
153
154 A document file in *.md format must start with a proper header defining a caption and a unique tag.
155
156 @verbatim
157 Documentation System {#dev_guides__documentation}
158 =====================
159 @endverbatim
160
161 The document structure is formed by sections that must be defined consistently.
162
163 The document can contain plain text, lists, tables, code snippets, images, math, etc.
164 Any specific text elements can be introduced by Markdown language tags or by usual HTML tags. 
165
166 The table of contents, page numbers (in PDF), and figure numbers (in PDF) are generated automatically.  
167
168 @subsection  OCCT_DM_SECTION_A_1 Headers and hierarchic document structure
169
170 Headers of different levels can be specified with the following tags:
171 * <i>\@section</i> -- for the first-level headers; 
172 * <i>\@subsection</i> -- for the second level headers;
173 * <i>\@subsubsection</i> -- for the third level headers.
174
175 For example:
176
177 @verbatim
178   @section occt_ocaf_1 Basic Concepts
179   @subsection occt_ocaf_1_1 Applications and Documents
180   @subsubsection occt_ocaf_1_1_1 The document and the data framework
181 @endverbatim
182
183 Please, note that section names can be used for references within the document and in other documents, so it is necessary to use the common prefix indicative of the document name for all section names in the given document. 
184 For example,  *occt_ocaf* for sections in Open CASCADE Application Framework manual.
185
186 The remaining part of section names in most documents consists only of numbers, for example *1_1*. Actually, the hierarchical structure of the output table of contents is not based on these numbers and is generated automatically. 
187
188 The numbers are only indicative of a section location in the body of the document. However, duplicate section names in a document inevitably cause errors during generation. 
189
190 If you insert a section in the middle of a big document, do not renumber the document to the end (which is inefficient and error prone), but choose an arbitrary number or letter, not yet used in the document section naming, and base the naming in this section on it.
191
192 The section hierarchy is limited to three levels and further levels cannot be presented in the Table of Contents.
193
194 However, the fourth and fifth level headers can be tagged with  <i>####</i> and <i>#####</i> correspondingly.
195
196 It is also possible to use tags <i>##</i> and <i>###</i> for second and third level headers if you do not wish to show them in the table of contents or make references to them. 
197
198 @subsection OCCT_DM_SECTION_A_2 Plain Text
199
200 A plain text is organized in paragraphs, separated by empty lines in MarkDown source.
201 The length of lines is not restricted; it is recommended to put each sentence on a separate line -- this is optimal for easier comparison of different versions of the same document.
202
203 To insert special symbols, like \< , \> or \\, prepend them with \\ character: \\\<, \\\>, \\\\, etc. 
204 To emphasize a word or a group of words, wrap the text with one pair of asterisks (*) or underscores (_) to make it *italic* and two pairs of these symbols to make it **Bold**.
205
206 **Note** that if your emphasized text starts or ends with a special symbol, the asterisks may not work. Use explicit HTML tags \<i\>\</i\>  and \<b\>\</b\>  instead.
207
208
209 @subsection OCCT_DM_SECTION_A_3 Lists
210
211 To create a bulleted list, start each line with a hyphen or an asterisk, 
212 followed by a space. List items can be nested. This code:
213
214 @verbatim
215 * Bullet 1
216 * Bullet 2
217   - Bullet 2a
218   - Bullet 2b
219 * Bullet 3
220 @endverbatim
221
222 produces this list:
223
224 * Bullet 1
225 * Bullet 2
226   * Bullet 2a
227   * Bullet 2b
228 * Bullet 3  
229
230 To create a numbered list, start each line with number and a period, 
231 then a space. Numbered lists can also be nested. Thus this code 
232
233 @verbatim
234 1. List item 1
235    1. Sub-item 1
236    2. Sub-item 2
237 2. List item 2
238 4. List item 3
239 @endverbatim
240
241 produces this list:
242
243 1. List item 1
244    1. Sub-item 1
245    2. Sub-item 2
246 2. List item 2
247 3. List item 3
248
249 **Note** that numbers of list items in the output are generated so they do not necessarily  follow the numbering of source items.
250
251 In some cases automatic generation adversely restarts the numbering, i.e. you get list items 1. 1. 1. instead of 1. 2. 3. in the output. 
252 The use of explicit HTML tags \<ol\>\</ol\> and  \<li\>\</li\> can help in this case. 
253
254 Each list item can contain several paragraphs of text; these paragraphs must 
255 have the same indentation as text after bullet or number in the numbered list 
256 item (otherwise numbering will be broken). 
257
258 Code blocks can be inserted as paragraphs with additional indentation 
259 (4 spaces more). Note that fenced code blocks do not work within numbered lists
260 and their use may cause numeration to be reset.
261
262
263 Example of a complex nested list:
264
265 1. List item 1
266
267    Additional paragraph
268
269        code fragment
270
271    One more paragraph
272
273    1. Sub-item 1
274
275           code fragment for sub-item 1
276
277    2. Sub-item 2
278
279       Paragraph for sub-item 2
280
281    Yet one more paragraph for list item 1
282
283 2. List item 2
284
285
286 @subsection  OCCT_DM_SECTION_A_4 Tables
287
288 A table consists of a header line, a separator line, and at least one row line. 
289 Table columns are separated by the pipe (|) character. The following example: 
290
291 @verbatim
292 First Header  | Second Header
293 ------------- | -------------
294 Content Cell  | Content Cell 
295 Content Cell  | Content Cell 
296 @endverbatim
297
298   will produce the following table:
299
300 First Header | Second Header
301 ------------ | -------------
302 Content Cell | Content Cell 
303 Content Cell | Content Cell 
304
305 Column alignment can be controlled via one or two colons at the header separator line: 
306
307 @verbatim
308 | Right | Center | Left  |
309 | ----: | :----: | :---- |
310 | 10    | 10     | 10    |
311 | 1000  | 1000   | 1000  |
312 @endverbatim
313
314 which will looks as follows:
315
316 | Right | Center | Left  |
317 | ----: | :----: | :---- |
318 | 10    | 10     | 10    |
319 | 1000  | 1000   | 1000  |
320
321 Note that each table row should be contained in one line of text; complex tables can be created using HTML tags.
322
323 @subsection  OCCT_DM_SECTION_A_5 Code Blocks
324
325 Paragraphs indented with 4 or more spaces are considered as code fragments and rendered using Courier font.
326 Example:
327     
328     This line is indented by 4 spaces and rendered as a code block.
329
330 A fenced code block does not require indentation, and is defined by a pair of "fence lines". 
331 Such line consists of 3 or more tilde (~) characters on a line. 
332 The end of the block should have the same number of tildes. 
333 Thus it is strongly advised to use only three or four tildes. 
334
335 By default the output is the same as for a normal code block.
336 To highlight the code, the developer has to indicate the typical file extension, 
337 which corresponds to the programming language, after the opening fence. 
338 For highlighting according to the C++ language, for instance,  write the following code (the curly braces and dot are optional): 
339
340 @verbatim
341 ~~~{.cpp}
342 int func(int a,int b) { return a*b; }
343 ~~~
344 @endverbatim
345
346 which will produce:
347 ~~~{.cpp} 
348 int func(int a,int b) { return a*b; }
349 ~~~
350
351 Smaller code blocks can be inserted by wrapping with tags <i>\@code</i> and <i>\@endcode</i>.
352
353 Verbatim content (same as code but without syntax highlighting) can be inserted by wrapping with tags <i>\@verbatim</i> and <i>\@endverbatim</i>.
354
355 @subsection  OCCT_DM_SECTION_A_6 References
356
357 To insert a reference to a website, it is sufficient to write an URL.
358 For example: http://en.wikipedia.org
359
360 To insert a reference to a document or its subsection, use command <i>\@ref</i> followed by the document or section tag name.
361 For instance, @code @ref OCCT_DM_SECTION_A @endcode will be rendered as @ref OCCT_DM_SECTION_A.
362
363 Note that links between documents will not work in PDF output if each document is generated independently.
364 Hence it is recommended to add a name of the referenced section after the tag name in the <i>\@ref</i> command (in quotes): this will guarantee that the reference is recognizable for the reader even if the cross-link is not instantiated. 
365 For instance: @code @ref occt_modat_1 "Geometry Utilities" @endcode will be rendered as @ref occt_modat_1 "Geometry Utilities".
366
367 @subsection  OCCT_DM_SECTION_A_7 Images
368
369 For inserting images into the document use the command <i>\@figure</i>, as follows:
370
371 @verbatim
372   @figure{/relative/path/to/image/image_file_name.png,"Image caption"}
373 @endverbatim
374
375 The first argument is a path to the image file, relative to the *dox* folder.
376 The supported formats for images are PNG, JPG, and SVG.
377 The file extension must be lowercase and correspond to the file format.
378 The image file name should have no dots except for the one before extension (names with more than one dot confuse **pdflatex**).
379
380 The second argument is optional, it defines the caption for the image to be inserted.
381 The caption argument, if given, should be quoted, even if it is a single word.
382 Captions are included below the image; in PDF output the images with caption are numbered automatically.
383
384 Example:
385
386 @verbatim
387   @figure{/dev_guides/documentation/images/documentation_test_image.svg,"Test SVG image"}
388 @endverbatim
389
390 is rendered as:
391
392 @figure{/dev_guides/documentation/images/documentation_test_image.svg,"Test SVG image",320}
393
394 We recommend using **Inkscape** for creation and edition of vector graphics.
395 The graphics created in MS Word Draw and some other vector editors can be copy-pasted to Inkscape and saved as SVG images.
396
397 Note that the image that will be included in documentation is the whole page of the Inkscape document; use option "Resize page to content" in menu **File -> Document properties** of Inkscape to fit page dimensions to the picture (adding margins as necessary).
398
399 Note that the *figure* command is an alias to the standard Doxygen command *image* repeated twice: once for HTML and then for Latex output (used for PDF generation). Thus if HTML and PDF outputs should include different images or captions, command "image" can be used:
400
401 @verbatim
402   @image html /relative/path/to/image/occ_logo_for_html.png
403   @image latex /relative/path/to/image/occ_logo_for_pdf.png
404 @endverbatim
405
406 @subsection  OCCT_DM_SECTION_A_8 Table Of Contents
407
408 Use \@tableofcontents tag to get the table of contents at the beginning of the document. 
409   
410 Actually, it is not strictly necessary 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. 
449
450   For example: 
451   
452 @verbatim
453   \begin{align}
454   \dot{x} & = \sigma(y-x) \\
455   \dot{y} & = \rho x - y - xz \\
456   \dot{z} & = -\beta z + xy
457   \end{align}
458 @endverbatim
459
460   gives the following result:
461 @latexonly
462   \begin{align}
463   \dot{x} & = \sigma(y-x) \\
464   \dot{y} & = \rho x - y - xz \\
465   \dot{z} & = -\beta z + xy
466   \end{align}
467 @endlatexonly
468
469 @htmlonly
470   \begin{align}
471   \dot{x} & = \sigma(y-x) \\
472   \dot{y} & = \rho x - y - xz \\
473   \dot{z} & = -\beta z + xy
474   \end{align}
475 @endhtmlonly
476
477 3.Inline formulas can be specified using this syntax:
478
479 @verbatim
480   @f$ \sqrt{3x-1}+(1+x)^2 @f$
481 @endverbatim
482
483   that leads to the following result: @f$ \sqrt{3x-1}+(1+x)^2 @f$
484