ceebd33dd5445975de2c71a7e1ef534c395cfa53
[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 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 **MiKTeX** or other package providing **pdflatex** command (only needed for generation of PDF documents): http://miktex.org/download
21
22 **Inkscape** (only needed for generation of PDF documents containing SVG images): http://www.inkscape.org/download
23
24 When generating PDF documentation, **pdflatex** and **inkscape** executables should be accessible by PATH variable.
25 You can use *custom.bat* file to add necessary paths to the *PATH* variable. 
26
27 Note that in the process of PDF generation MiKTeX may need some packages not installed by default.
28 We recommend setting option "Install missing packages on-the-fly" to "Ask me first" (default) during MiKTeX installation:
29
30 @figure{/dev_guides/documentation/images/documentation_miktex.png}
31
32 On the first run of **pdflatex** it will open a dialog window prompting for installation of missing packages.
33 Follow the instructions to proceed (define proxy settings if needed, select a mirror site to download from, etc.).
34
35 **MathJax** is used for rendering math formulas in browser (HTML and CHM outputs): http://www.mathjax.org.
36
37 By default MathJAX scripts and fonts are taken from http://cdn.mathjax.org/mathjax/latest and no installation of MathJAX is necessary if Internet is accessible.
38 If you need to use OCCT documentation while off-line, you can install a local copy of MatJAX, see http://www.mathjax.org/download/.
39 See \ref OCCT_DM_SECTION_A_9 for more details on inserting mathematical expressions. 
40
41 @section OCCT_DM_SECTION_2_1 Documentation Generation
42
43 Run *gendoc.bat* from OCCT directory to generate all documents defined in *FILES.txt*:
44
45 *gendoc.bat* can be started with the following options:
46
47   * <i>-html</i>                : Generates HTML files (cannot be used with -pdf);
48   * <i>-pdf</i>                 : Generates PDF files (cannot be used with -html);
49   * <i>-m=\<modules_list\></i>  : Specifies the list of documents to generate. If it is not specified, all files mentioned in *FILES.txt* are processed;
50   * <i>-l=\<document_name\></i> : Specifies the output document title;
51   * <i>-mathjax=\<path\></i>    : Specifies the path to a non-default location of MathJAX;
52   * <i>-h</i>                   : Prints a help message;
53   * <i>-v</i>                   : Toggles the Verbose mode (info on all script actions is shown).
54
55 If you run the command without arguments (like in the example above) it will generate HTML documentation for all documents defined in *FILES.txt*.
56
57 **Note**
58
59 * In case of a PDF output the utility generates a separate PDF file for each document;
60 * In case of an HTML output the utility generates a common Table of contents containing references to all documents.
61
62 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:
63
64 ~~~~
65     % gendoc.bat -html -m=dev_guides/documentation/documentation.md
66 ~~~~
67
68 Multiple files can be separated with commas:
69 ~~~~
70     % gendoc.bat -html -m=MD_FILE_1,MD_FILE_2
71 ~~~~
72
73 Use quotes to specify an article name with <i>-l</i> option, which helps to prevent incorrect interpretation of white spaces:
74
75 ~~~~
76     % gendoc.bat -pdf -m=MD_FILE_1 -l="Label of MD_FILE_1 document"
77 ~~~~
78
79 @section  OCCT_DM_SECTION_3 Documentation Conventions
80
81 This section contains information about file format conventions, directories structure, etc.
82
83 @subsection  OCCT_DM_SECTION_3_1 File Format
84
85 The format used for documentation is MarkDown with Doxygen extensions. 
86 The MarkDown files have a <i>*.md</i> extension and are based on rules described in \ref OCCT_DM_SECTION_A section.
87
88 @subsection  OCCT_DM_SECTION_3_2 Directory Structure
89
90 @figure{/dev_guides/documentation/images/documentation_folders.png}
91
92 Each document has its own folder if there are any images used in it. These images are stored in *images* subfolder.
93
94 If you want to use the same image for several documents, you can place it in *dox/resources* folder.
95
96 **Note**: To avoid incorrect image display, use a relative path to the image (starting from *dox* folder). For instance:
97
98
99 @verbatim
100 @figure{/dev_guides/documentation/images/documentation_test_image.svg}
101 @endverbatim
102
103
104 The documentation is generated in subfolder *doc* :
105 * *html* - a directory for generated HTML pages;
106 * *pdf* - a directory for generated PDF files.
107
108 @section  OCCT_DM_SECTION_4 Adding a New Document
109
110 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>. 
111
112 If there are images in the document, it should be placed in its own folder containing a subfolder for images. For instance:
113 * <i> /dox/dev_guides/svn/ </i> - for *svn.md* file;
114 * <i> /dox/dev_guides/svn/images/ </i> - for images.
115
116 Add a relative path to *svn.md* in file <i>dox/FILES.txt</i>. For instance
117
118 @verbatim
119 dev_guides/svn/svn.md
120 @endverbatim
121
122 **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.
123
124 **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.
125
126 @section  OCCT_DOC_SECTION_5 Additional Resources
127
128 More information about OCCT can be found at http://www.opencascade.org
129
130 The information on formula syntax can be found at: 
131 http://en.wikipedia.org/wiki/Help:Displaying_a_formula
132
133 More information on MarkDown and Doxygen syntax can be found at:
134 http://www.stack.nl/~dimitri/doxygen/manual
135
136 @section  OCCT_DM_SECTION_A Appendix 1: Document Syntax
137
138 A document file in *.md format must start with a proper header defining a caption and a unique tag.
139
140 @verbatim
141 Documentation System {#dev_guides__documentation}
142 =====================
143 @endverbatim
144
145 The document structure is formed by sections that must be defined consistently.
146
147 The document can contain plain text, lists, tables, code snippets, images, math, etc.
148 Any specific text elements can be introduced by Markdown language tags or by usual HTML tags. 
149
150 The table of contents, page numbers (in PDF), and figure numbers (in PDF) are generated automatically.  
151
152 @subsection  OCCT_DM_SECTION_A_1 Headers and hierarchic document structure
153
154 Headers of different levels can be specified with the following tags:
155 * <i>\@section</i> - for the first-level headers; 
156 * <i>\@subsection</i> - for the second level headers;
157 * <i>\@subsubsection</i> - for the third level headers.
158
159 For example:
160
161 @verbatim
162   @section occt_ocaf_1 Basic Concepts
163   @subsection occt_ocaf_1_1 Applications and Documents
164   @subsubsection occt_ocaf_1_1_1 The document and the data framework
165 @endverbatim
166
167 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. 
168 For example,  *occt_ocaf* for sections in Open CASCADE Application Framework manual.
169
170 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. 
171
172 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. 
173
174 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.
175
176 The section hierarchy is limited to three levels and further levels cannot be presented in the Table of Contents.
177
178 However, the fourth and fifth level headers can be tagged with  <i>####</i> and <i>#####</i> correspondingly.
179
180 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. 
181
182 @subsection OCCT_DM_SECTION_A_2 Plain Text
183
184 A plain text is organized in paragraphs, separated by empty lines in MarkDown source.
185 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.
186
187 To insert special symbols, like \< , \> or \\, prepend them with \\ character: \\\<, \\\>, \\\\, etc. 
188 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**.
189
190 **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.
191
192
193 @subsection OCCT_DM_SECTION_A_3 Lists
194
195 To create a bulleted list, start each line with a hyphen or an asterisk, 
196 followed by a space. List items can be nested. This code:
197
198 @verbatim
199 * Bullet 1
200 * Bullet 2
201   - Bullet 2a
202   - Bullet 2b
203 * Bullet 3
204 @endverbatim
205
206 produces this list:
207
208 * Bullet 1
209 * Bullet 2
210   * Bullet 2a
211   * Bullet 2b
212 * Bullet 3  
213
214 To create a numbered list, start each line with number and a period, 
215 then a space. Numbered lists can also be nested. Thus this code 
216
217 @verbatim
218 1. List item 1
219    1. Sub-item 1
220    2. Sub-item 2
221 2. List item 2
222 4. List item 3
223 @endverbatim
224
225 produces this list:
226
227 1. List item 1
228    1. Sub-item 1
229    2. Sub-item 2
230 2. List item 2
231 3. List item 3
232
233 **Note** that numbers of list items in the output are generated so they do not necessarily  follow the numbering of source items.
234
235 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. 
236 The use of explicit HTML tags \<ol\>\</ol\> and  \<li\>\</li\> can help in this case. 
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 a complex nested list:
248
249 1. List item 1
250
251    Additional paragraph
252
253        code fragment
254
255    One more paragraph
256
257    1. Sub-item 1
258
259           code fragment for sub-item 1
260
261    2. Sub-item 2
262
263       Paragraph for sub-item 2
264
265    Yet one more paragraph for list item 1
266
267 2. List item 2
268
269
270 @subsection  OCCT_DM_SECTION_A_4 Tables
271
272 A table consists of a header line, a separator line, and at least one row line. 
273 Table columns are separated by the pipe (|) character. The following example: 
274
275 @verbatim
276 First Header  | Second Header
277 ------------- | -------------
278 Content Cell  | Content Cell 
279 Content Cell  | Content Cell 
280 @endverbatim
281
282   will produce the following table:
283
284 First Header | Second Header
285 ------------ | -------------
286 Content Cell | Content Cell 
287 Content Cell | Content Cell 
288
289 Column alignment can be controlled via one or two colons at the header separator line: 
290
291 @verbatim
292 | Right | Center | Left  |
293 | ----: | :----: | :---- |
294 | 10    | 10     | 10    |
295 | 1000  | 1000   | 1000  |
296 @endverbatim
297
298 which will looks as follows:
299
300 | Right | Center | Left  |
301 | ----: | :----: | :---- |
302 | 10    | 10     | 10    |
303 | 1000  | 1000   | 1000  |
304
305 Note that each table row should be contained in one line of text; complex tables can be created using HTML tags.
306
307 @subsection  OCCT_DM_SECTION_A_5 Code Blocks
308
309 Paragraphs indented with 4 or more spaces are considered as code fragments and rendered using Courier font.
310 Example:
311     
312     This line is indented by 4 spaces and rendered as a code block.
313
314 A fenced code block does not require indentation, and is defined by a pair of "fence lines". 
315 Such line consists of 3 or more tilde (~) characters on a line. 
316 The end of the block should have the same number of tildes. 
317 Thus it is strongly advised to use only three or four tildes. 
318
319 By default the output is the same as for a normal code block.
320 To highlight the code, the developer has to indicate the typical file extension, 
321 which corresponds to the programming language, after the opening fence. 
322 For highlighting according to the C++ language, for instance,  write the following code (the curly braces and dot are optional): 
323
324 @verbatim
325 ~~~{.cpp}
326 int func(int a,int b) { return a*b; }
327 ~~~
328 @endverbatim
329
330 which will produce:
331 ~~~{.cpp} 
332 int func(int a,int b) { return a*b; }
333 ~~~
334
335 Smaller code blocks can be inserted by wrapping with tags <i>\@code</i> and <i>\@endcode</i>.
336
337 Verbatim content (same as code but without syntax highlighting) can be inserted by wrapping with tags <i>\@verbatim</i> and <i>\@endverbatim</i>.
338
339 @subsection  OCCT_DM_SECTION_A_6 References
340
341 To insert a reference to a website, it is sufficient to write an URL.
342 For example: http://en.wikipedia.org
343
344 To insert a reference to a document or its subsection, use command <i>\@ref</i> followed by the document or section tag name.
345 For instance, @code @ref OCCT_DM_SECTION_A @endcode will be rendered as @ref OCCT_DM_SECTION_A.
346
347 Note that links between documents will not work in PDF output if each document is generated independently.
348 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. 
349 For instance: @code @ref occt_modat_1 "Geometry Utilities" @endcode will be rendered as @ref occt_modat_1 "Geometry Utilities".
350
351 @subsection  OCCT_DM_SECTION_A_7 Images
352
353 For inserting images into the document use the command <i>\@figure</i>, as follows:
354
355 @verbatim
356   @figure{/relative/path/to/image/image_file_name.png,"Image caption"}
357 @endverbatim
358
359 The first argument is a path to the image file, relative to the *dox* folder.
360 The supported formats for images are PNG, JPG, and SVG.
361 The file extension must be lowercase and correspond to the file format.
362 The image file name should have no dots except for the one before extension (names with more than one dot confuse **pdflatex**).
363
364 The second argument is optional, it defines the caption for the image to be inserted.
365 The caption argument, if given, should be quoted, even if it is a single word.
366 Captions are included below the image; in PDF output the images with caption are numbered automatically.
367
368 Example:
369
370 @verbatim
371   @figure{/dev_guides/documentation/images/documentation_test_image.svg,"Test SVG image"}
372 @endverbatim
373
374 is rendered as:
375
376 @figure{/dev_guides/documentation/images/documentation_test_image.svg,"Test SVG image"}
377
378 We recommend using **Inkscape** for creation and edition of vector graphics.
379 The graphics created in MS Word Draw and some other vector editors can be copy-pasted to Inkscape and saved as SVG images.
380
381 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).
382
383 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:
384
385 @verbatim
386   @image html /relative/path/to/image/occ_logo.png
387   @image latex /relative/path/to/image/occ_logo.png "OCC logo"
388 @endverbatim
389
390 @image html /resources/occ_logo.png
391 @image latex /resources/occ_logo.png "OCC logo"
392  
393 @subsection  OCCT_DM_SECTION_A_8 Table Of Contents
394
395 Use \@tableofcontents tag to get the table of contents at the beginning of the document. 
396   
397 Actually, it is not strictly necessary now because TreeView option for HTML is used.
398 The TOC in the PDF document will be generated automatically.
399
400 @subsection  OCCT_DM_SECTION_A_9 Formulas
401
402 Formulas within MarkDown documents can be defined using LaTeX syntax.
403
404 Equations can be written by several ways:
405
406 1.Unnumbered displayed formulas that are centered on a separate line. 
407 These formulas should be put between \@f\[ and \@f\] tags. An example: 
408
409 @verbatim
410 @f[
411     |I_2|=\left| \int_{0}^T \psi(t)
412             \left\{ 
413                 u(a,t)-
414                 \int_{\gamma(t)}^a 
415                 \frac{d\theta}{k(\theta,t)}
416                 \int_{a}^\theta c(\xi)u_t(\xi,t)\,d\xi
417             \right\} dt
418         \right|
419 @f]
420 @endverbatim
421
422 gives the following result:
423
424    @f$
425        |I_2|=\left| \int_{0}^T \psi(t)
426                \left\{ 
427                    u(a,t)-
428                    \int_{\gamma(t)}^a 
429                    \frac{d\theta}{k(\theta,t)}
430                    \int_{a}^\theta c(\xi)u_t(\xi,t)\,d\xi
431                \right\} dt
432            \right|
433    @f$
434    
435 2.Formulas can also be put between @verbatim \begin{align} @endverbatim and @verbatim \end{align} @endverbatim tags. 
436
437   For example: 
438   
439 @verbatim
440   \begin{align}
441   \dot{x} & = \sigma(y-x) \\
442   \dot{y} & = \rho x - y - xz \\
443   \dot{z} & = -\beta z + xy
444   \end{align}
445 @endverbatim
446
447   gives the following result:
448 @latexonly
449   \begin{align}
450   \dot{x} & = \sigma(y-x) \\
451   \dot{y} & = \rho x - y - xz \\
452   \dot{z} & = -\beta z + xy
453   \end{align}
454 @endlatexonly
455
456 @htmlonly
457   \begin{align}
458   \dot{x} & = \sigma(y-x) \\
459   \dot{y} & = \rho x - y - xz \\
460   \dot{z} & = -\beta z + xy
461   \end{align}
462 @endhtmlonly
463
464 3.Inline formulas can be specified using this syntax:
465
466 @verbatim
467   @f$ \sqrt{3x-1}+(1+x)^2 @f$
468 @endverbatim
469
470   that leads to the following result: @f$ \sqrt{3x-1}+(1+x)^2 @f$
471