e5bd0d98 |
1 | Documentation System {#dev_guides__documentation} |
2 | ====================== |
3 | |
4 | @tableofcontents |
72b7576f |
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 | <b>Tcl/Tk</b> |
e5bd0d98 |
13 | Version 8.5 or 8.6: http://www.tcl.tk/software/tcltk/download.html |
72b7576f |
14 | |
e5bd0d98 |
15 | <b>Doxygen</b> |
16 | Version 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). |
19 | See \ref OCCT_DM_SECTION_A_9 paragraph for more detailed description. |
72b7576f |
20 | The latest version: http://www.mathjax.org/download/ |
21 | |
22 | <b>MiKTeX</b> or equivalent tool (used for PDF document creation) |
e5bd0d98 |
23 | |
72b7576f |
24 | Latest 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 |
28 | MiKTeX 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 | |
33 | If 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 | |
37 | Run gendoc.bat from OCCT directory to generate all articles are defined in FILES.txt: |
38 | |
39 | gendoc.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 | |
48 | If you run the command without arguments (like example above) it will generate HTML documentation |
49 | for all articles are defined into FILES.txt. |
50 | |
51 | **Note**: the generation process generates PDF files for each article, |
52 | but in html case it generates common Html page with references to the ones. |
53 | |
54 | For 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 |
59 | devs_guid/documentation/documentation.md |
60 | @endverbatim |
61 | |
62 | where 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 | |
70 | Multiple 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 |
76 | To 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 | |
84 | This section contains information about conventions in the field of OCCT documentation file format, |
85 | structure of documentation directories, etc. |
86 | |
87 | @subsection OCCT_DM_SECTION_3_1 File Format |
88 | |
79d580f2 |
89 | The format used for documentation is MarkDown with Doxygen extensions. |
72b7576f |
90 | The 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 | |
98 | Every separate article has own folder if images are used in it. These images |
99 | are stored into "images" subfolder. |
100 | |
101 | If 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 |
104 | displaying, 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 | |
109 | Result 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 |
118 | at the hierarchy of the documentation. For instance the article about "using SVN working with OCCT |
dba69de2 |
119 | 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 |
72b7576f |
120 | the 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 |
126 | dev_guides/snv/svn.md |
72b7576f |
127 | @endverbatim |
128 | |
129 | **Note**: the place of the relative path to an article is connected with the place |
130 | into treeview of html version. |
131 | |
132 | |
133 | Note, that you should specify a file tag, not the document name. |
134 | See <a href="#OCCT_DM_SECTION_A_1">Header section</a> for details. |
135 | |
136 | @section OCCT_DOC_SECTION_5 Additional Resources |
137 | |
138 | More information about OCCT can be found at http://www.opencascade.org |
139 | |
140 | The information on formula syntax can be found at: |
141 | http://en.wikipedia.org/wiki/Help:Displaying_a_formula |
142 | |
143 | More information on MarkDown and Doxygen syntax can be found at: |
144 | http://www.stack.nl/~dimitri/doxygen/manual |
e5bd0d98 |
145 | |
146 | @section OCCT_DM_SECTION_A Appendix 1: Document Syntax |
147 | |
148 | Each OCCT document file in *.md format has a simple structure. |
149 | It 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 | |
164 | The 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 | |
171 | headings of different levels can be specified with the following code: |
172 | |
173 | @verbatim |
174 | Header 1 {#header1} |
175 | ======= |
176 | @endverbatim |
177 | |
178 | to get |
179 | |
180 | Header 1 |
181 | ========= |
182 | |
183 | and with the following code: |
184 | |
185 | @verbatim |
186 | Header 2 {#header2} |
187 | -------- |
188 | @endverbatim |
189 | |
190 | to get |
191 | |
192 | Header 2 |
193 | --------- |
194 | |
195 | Where a word in curly braces is a MarkDown-style reference, which can be used in table of contents. |
196 | If 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 | |
207 | Plain text is a text in a notepad-like format. To insert special symbols, |
208 | like \< , \> or \\, prepend them with \\ character: \\\<, \\\>, \\\\ |
209 | To emphasize some words, write one pair of asterisks ( * ) or underscores ( _ ) across the word |
210 | to make it *italic* and two pairs of these symbols to make a word **Bold**. |
211 | |
212 | @subsection OCCT_DM_SECTION_A_3 Lists |
213 | |
214 | To create a bulleted list, start each line with a hyphen or an asterisk, |
215 | followed 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 |
225 | produces this list: |
e5bd0d98 |
226 | |
79d580f2 |
227 | * Bullet 1 |
228 | * Bullet 2 |
229 | * Bullet 2a |
230 | * Bullet 2b |
231 | * Bullet 3 |
e5bd0d98 |
232 | |
79d580f2 |
233 | To create a numbered list, start each line with number and a period, |
234 | then a space. Numbered lists can also be nested. Thus this code |
e5bd0d98 |
235 | |
236 | @verbatim |
79d580f2 |
237 | 1. List item 1 |
238 | 1. Sub-item 1 |
239 | 2. Sub-item 2 |
240 | 2. List item 2 |
241 | 3. List item 3 |
e5bd0d98 |
242 | @endverbatim |
243 | |
79d580f2 |
244 | produces this list: |
e5bd0d98 |
245 | |
79d580f2 |
246 | 1. List item 1 |
247 | 1. Sub-item 1 |
248 | 2. Sub-item 2 |
249 | 2. List item 2 |
250 | 3. List item 3 |
e5bd0d98 |
251 | |
79d580f2 |
252 | Each list item can contain several paragraphs of text; these paragraphs must |
253 | have the same indentation as text after bullet or number in the numbered list |
254 | item (otherwise numbering will be broken). |
255 | |
256 | Code blocks can be inserted as paragraphs with additional indentation |
257 | (4 spaces more). Note that fenced code blocks do not work within numbered lists |
258 | and their use may cause numeration to be reset. |
259 | |
260 | |
261 | Example of complex nested list: |
262 | |
263 | @verbatim |
264 | 1. 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 | |
282 | 2. ListItem_2 |
283 | @endverbatim |
284 | |
285 | 1. 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 | |
303 | 2. List item 2 |
304 | |
305 | Note that numbers of paragraphs are regenerated so they do not necessarily |
306 | follow numbering of source items. |
e5bd0d98 |
307 | |
308 | @subsection OCCT_DM_SECTION_A_4 Tables |
309 | |
310 | A table consists of a header line, a separator line, and at least one row line. |
311 | Table columns are separated by the pipe (|) character. The following example: |
312 | |
313 | @verbatim |
314 | First Header | Second Header |
315 | ------------- | ------------- |
316 | Content Cell | Content Cell |
317 | Content Cell | Content Cell |
318 | @endverbatim |
319 | |
320 | will produce the following table: |
321 | |
322 | First Header | Second Header |
323 | ------------ | ------------- |
324 | Content Cell | Content Cell |
325 | Content Cell | Content Cell |
326 | |
327 | Column 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 | |
336 | which will looks as follows: |
337 | |
338 | | Right | Center | Left | |
339 | | ----: | :----: | :---- | |
340 | | 10 | 10 | 10 | |
341 | | 1000 | 1000 | 1000 | |
342 | |
79d580f2 |
343 | Note that each table raw should be contained in one line of text; complex |
344 | tables can be created using HTML tags. |
345 | |
e5bd0d98 |
346 | @subsection OCCT_DM_SECTION_A_5 Code Blocks |
347 | |
348 | It is recommended to indent a code lines with 4 spaces. |
349 | A fenced code block does not require indentation, and is defined by a pair of "fence lines". |
350 | Such line consists of 3 or more tilde (~) characters on a line. |
351 | The 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 | |
357 | By default the output is the same as for a normal code block. |
358 | To highlight the code, the developer has to indicate the typical file extension, |
359 | which corresponds to the programming language, after the opening fence. |
360 | For highlighting according to the C++ language, for instance, write the following code (the curly braces and dot are optional): |
361 | |
362 | @verbatim |
363 | ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~{.cpp} |
bb27b807 |
364 | int func(int a,int b) { return a*b; } |
e5bd0d98 |
365 | ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ |
366 | @endverbatim |
367 | |
368 | which will produce: |
369 | ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~{.cpp} |
bb27b807 |
370 | int func(int a,int b) { return a*b; } |
e5bd0d98 |
371 | ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ |
372 | |
373 | Verbatim content can be written by using framing \@verbatim \@endverbatim . For instance |
374 | |
bb27b807 |
375 | verbatim text |
376 | |
e5bd0d98 |
377 | |
378 | @subsection OCCT_DM_SECTION_A_6 References |
379 | |
380 | To insert a reference to a website, it is proposed to write a URL. For example: http://en.wikipedia.org |
381 | To insert a reference to another part of the same document, the developer can write: |
382 | |
383 | @verbatim |
384 | @htmlonly |
385 | <a href="#OCCT_DOC_SECTION_5">Doxygen Configuration file</a> |
386 | @endhtmlonly |
387 | @endverbatim |
388 | |
389 | to get a link to paragraph : @htmlonly <a href="#OCCT_DOC_SECTION_5">Doxygen configuration</a> @endhtmlonly |
390 | |
391 | @subsection OCCT_DM_SECTION_A_7 Images |
392 | |
393 | To insert image into document the developer can write the following code(in Doxygen-style): |
bb27b807 |
394 | |
395 | For HTML document: |
396 | @verbatim |
397 | @image html /relative/path/to/image/image001.png "Image caption" |
398 | @endverbatim |
399 | |
400 | For latex document: |
401 | @verbatim |
402 | @image latex /relative/path/to/image/image001.png "Image caption" |
403 | @endverbatim |
404 | |
405 | *Note*: When markdown document is used to generate html document the latex insertion is ignored (and vice versa) |
406 | due to this fact you can use image insertions in the pair, like example below: |
e5bd0d98 |
407 | @verbatim |
bb27b807 |
408 | @image html /relative/path/to/image/image001.png "Image caption" |
409 | @image latex /relative/path/to/image/image001.png "Image caption" |
e5bd0d98 |
410 | @endverbatim |
411 | |
bb27b807 |
412 | The code below tells Doxygen to insert a picture right in the place this code was written: |
e5bd0d98 |
413 | @verbatim |
bb27b807 |
414 | @image html /resources/occ_logo.png "OCCT logo" |
415 | @image latex /resources/occ_logo.png "OCCT logo" |
e5bd0d98 |
416 | @endverbatim |
417 | |
bb27b807 |
418 | @image html /resources/occ_logo.png "OCCT logo" |
419 | @image latex /resources/occ_logo.png "OCCT logo" |
e5bd0d98 |
420 | |
421 | @subsection OCCT_DM_SECTION_A_8 Table Of Contents |
422 | |
423 | To get the table of contents at the beginning of the document, write \@tableofcontents tag. |
424 | But it is not needed now because TreeView option for HTML is used. |
425 | The TOC in the PDF document will be generated automatically. |
426 | |
427 | @subsection OCCT_DM_SECTION_A_9 Formulas |
428 | |
429 | Formulas within documents will be generated using MathJax tool. |
430 | |
431 | A developer has to specify these parameters in Doxyfile to enable support of MathJax in Doxygen: |
432 | |
433 | USE_MATHJAX = YES |
434 | MATHJAX_FORMAT = HTML-CSS |
435 | MATHJAX_RELPATH = http://cdn.mathjax.org/mathjax/latest |
436 | MATHJAX_EXTENSIONS = TeX/AMSmath TeX/AMSsymbols |
437 | |
438 | To use MathJax tool with the HTML page, it's \<head\> block has to contain |
439 | |
440 | ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~{.html} |
441 | <script type="text/x-mathjax-config"> |
442 | MathJax.Hub.Config({ |
443 | tex2jax: {inlineMath: [["$","$"],["\\(","\\)"]]}, |
444 | displayAlign: "left" |
445 | }); |
446 | </script> |
447 | |
448 | <script type="text/javascript" |
449 | src="http://cdn.mathjax.org/mathjax/latest/MathJax.js?config=TeX-AMS-MML_HTMLorMML"> |
450 | </script> |
451 | ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ |
452 | |
453 | First script configures MathJax to understand separator types and to left allign formulas. |
454 | The second script inserts reference to MathJax tool. |
455 | This tool will always be used when the HTML output will be shown. |
456 | |
457 | Equations can be written by several ways: |
458 | |
459 | 1.Unnumbered displayed formulas that are centered on a separate line. |
460 | These formulas should be put between \@f\[ and \@f\] tags. An example: |
461 | |
462 | @verbatim |
dd21889e |
463 | @f[ |
e5bd0d98 |
464 | |I_2|=\left| \int_{0}^T \psi(t) |
465 | \left\{ |
466 | u(a,t)- |
467 | \int_{\gamma(t)}^a |
468 | \frac{d\theta}{k(\theta,t)} |
469 | \int_{a}^\theta c(\xi)u_t(\xi,t)\,d\xi |
470 | \right\} dt |
471 | \right| |
dd21889e |
472 | @f] |
e5bd0d98 |
473 | @endverbatim |
474 | |
475 | gives the following result: |
476 | |
477 | @f$ |
478 | |I_2|=\left| \int_{0}^T \psi(t) |
479 | \left\{ |
480 | u(a,t)- |
481 | \int_{\gamma(t)}^a |
482 | \frac{d\theta}{k(\theta,t)} |
483 | \int_{a}^\theta c(\xi)u_t(\xi,t)\,d\xi |
484 | \right\} dt |
485 | \right| |
486 | @f$ |
487 | |
488 | 2.Formulas can also be put between @verbatim \begin{align} @endverbatim and @verbatim \end{align} @endverbatim tags. An example: |
489 | |
490 | @verbatim |
491 | \begin{align} |
492 | \dot{x} & = \sigma(y-x) \\ |
493 | \dot{y} & = \rho x - y - xz \\ |
494 | \dot{z} & = -\beta z + xy |
495 | \end{align} |
496 | @endverbatim |
497 | |
498 | gives the following result: |
499 | @latexonly |
500 | \begin{align} |
501 | \dot{x} & = \sigma(y-x) \\ |
502 | \dot{y} & = \rho x - y - xz \\ |
503 | \dot{z} & = -\beta z + xy |
504 | \end{align} |
505 | @endlatexonly |
506 | |
507 | @htmlonly |
508 | \begin{align} |
509 | \dot{x} & = \sigma(y-x) \\ |
510 | \dot{y} & = \rho x - y - xz \\ |
511 | \dot{z} & = -\beta z + xy |
512 | \end{align} |
513 | @endhtmlonly |
514 | |
515 | 3.Inline formulas can be specified using this syntax: |
516 | |
517 | @verbatim |
518 | @f$ \sqrt{3x-1}+(1+x)^2 @f$ |
519 | @endverbatim |
520 | |
521 | that leads to the following result: @f$ \sqrt{3x-1}+(1+x)^2 @f$ |
522 | |