0028951: MathJax CDN shutting down
[occt.git] / dox / dev_guides / documentation / documentation.md
CommitLineData
ba06f8bb 1 Documentation System {#occt_dev_guides__documentation}
e5bd0d98 2======================
3
4@tableofcontents
72b7576f 5
6@section OCCT_DM_SECTION_1 Introduction
7
3d68eaf5 8This document provides practical guidelines for generation and editing of OCCT user documentation.
72b7576f 9
10@section OCCT_DM_SECTION_2 Prerequisites
11
3d68eaf5 12You need to have the following software installed to generate the documentation.
e8181411 13
3d68eaf5 14**Tcl/Tk**
e5bd0d98 15Version 8.5 or 8.6: http://www.tcl.tk/software/tcltk/download.html
72b7576f 16
3d68eaf5 17**Doxygen**
e5bd0d98 18Version 1.8.4 or above: http://www.stack.nl/~dimitri/doxygen/download.html
72b7576f 19
77906c4c 20**Dot**
21Part of Graphviz software, used by Doxygen for generation of class diagrams in Reference Manual: http://www.graphviz.org/Download..php
22
3d68eaf5 23**MiKTeX** or other package providing **pdflatex** command (only needed for generation of PDF documents): http://miktex.org/download
72b7576f 24
3d68eaf5 25**Inkscape** (only needed for generation of PDF documents containing SVG images): http://www.inkscape.org/download
e5bd0d98 26
3d68eaf5 27When generating PDF documentation, **pdflatex** and **inkscape** executables should be accessible by PATH variable.
28You can use *custom.bat* file to add necessary paths to the *PATH* variable.
e5bd0d98 29
3d68eaf5 30Note that in the process of PDF generation MiKTeX may need some packages not installed by default.
31We recommend setting option "Install missing packages on-the-fly" to "Ask me first" (default) during MiKTeX installation:
dba69de2 32
d6b4d3d0 33@figure{/dev_guides/documentation/images/documentation_miktex.png,"",320}
e8181411 34
3d68eaf5 35On the first run of **pdflatex** it will open a dialog window prompting for installation of missing packages.
36Follow 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
251a7984 40By default MathJAX scripts and fonts work on-line and no installation of MathJAX is necessary if Internet is accessible.
bbf03a4e 41If you need to use OCCT documentation while off-line, you can install a local copy of MatJAX, see https://docs.mathjax.org/en/v2.7-latest/start.html#installing-your-own-copy-of-mathjax.
3d68eaf5 42See \ref OCCT_DM_SECTION_A_9 for more details on inserting mathematical expressions.
e8181411 43
72b7576f 44@section OCCT_DM_SECTION_2_1 Documentation Generation
45
ba06f8bb 46Run command *gendoc* from command prompt (with OCCT directory as current one) to generate OCCT documentation.
47The synopsis is:
72b7576f 48
ba06f8bb 49 gendoc \[-h\] {-refman|-overview} \[-html|-pdf|-chm\] \[-m=<list of modules>|-ug=<list of docs>\] \[-v\] \[-s=<search_mode>\] \[-mathjax=<path>\]
50
51Here the options are:
72b7576f 52
ba06f8bb 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)
72b7576f 56
ba06f8bb 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
72b7576f 69
3d68eaf5 70**Note**
72b7576f 71
ba06f8bb 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**
72b7576f 77
3d68eaf5 78To 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:
72b7576f 79
3d68eaf5 80~~~~
ba06f8bb 81 > gendoc -overview -ug=dev_guides/documentation/documentation.md
3d68eaf5 82~~~~
72b7576f 83
ba06f8bb 84To generate Reference Manual for the whole Open CASCADE Technology library, run:
3d68eaf5 85~~~~
ba06f8bb 86 > gendoc -refman
3d68eaf5 87~~~~
72b7576f 88
ba06f8bb 89To generate Reference Manual for Foundation Classes and Modeling Data modules only, with search option, run:
3d68eaf5 90~~~~
ba06f8bb 91 > gendoc -refman -m=FoundationClasses,ModelingData,ModelingAlgorithms -s=local
3d68eaf5 92~~~~
72b7576f 93
94@section OCCT_DM_SECTION_3 Documentation Conventions
95
3d68eaf5 96This section contains information about file format conventions, directories structure, etc.
72b7576f 97
98@subsection OCCT_DM_SECTION_3_1 File Format
99
79d580f2 100The format used for documentation is MarkDown with Doxygen extensions.
3d68eaf5 101The MarkDown files have a <i>*.md</i> extension and are based on rules described in \ref OCCT_DM_SECTION_A section.
72b7576f 102
103@subsection OCCT_DM_SECTION_3_2 Directory Structure
104
d6b4d3d0 105@figure{/dev_guides/documentation/images/documentation_folders.png,"",160}
72b7576f 106
3d68eaf5 107Each document has its own folder if there are any images used in it. These images are stored in *images* subfolder.
108
109If 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:
72b7576f 112
72b7576f 113
72b7576f 114@verbatim
d6b4d3d0 115@figure{/dev_guides/documentation/images/documentation_test_image.svg,"",420}
72b7576f 116@endverbatim
117
72b7576f 118
3d68eaf5 119The documentation is generated in subfolder *doc* :
3f812249 120* *html* -- a directory for generated HTML pages;
121* *pdf* -- a directory for generated PDF files.
3d68eaf5 122
123@section OCCT_DM_SECTION_4 Adding a New Document
124
125Place 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>.
72b7576f 126
3d68eaf5 127If there are images in the document, it should be placed in its own folder containing a subfolder for images. For instance:
3f812249 128* <i> /dox/dev_guides/svn/ </i> -- for *svn.md* file;
129* <i> /dox/dev_guides/svn/images/ </i> -- for images.
72b7576f 130
3d68eaf5 131Add a relative path to *svn.md* in file <i>dox/FILES.txt</i>. For instance
72b7576f 132
72b7576f 133@verbatim
3d68eaf5 134dev_guides/svn/svn.md
72b7576f 135@endverbatim
136
3d68eaf5 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.
72b7576f 138
67d7f07f 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.
72b7576f 140
141@section OCCT_DOC_SECTION_5 Additional Resources
142
d6b4d3d0 143More information about OCCT can be found at http://www.opencascade.com and <br> http://dev.opencascade.org sites.
e2ba9cb1 144
72b7576f 145
d6b4d3d0 146The information on formula syntax can be found at: <br>
72b7576f 147http://en.wikipedia.org/wiki/Help:Displaying_a_formula
148
d6b4d3d0 149More information on MarkDown and Doxygen syntax can be found at: <br>
72b7576f 150http://www.stack.nl/~dimitri/doxygen/manual
e5bd0d98 151
152@section OCCT_DM_SECTION_A Appendix 1: Document Syntax
153
3d68eaf5 154A document file in *.md format must start with a proper header defining a caption and a unique tag.
155
156@verbatim
157Documentation System {#dev_guides__documentation}
158=====================
159@endverbatim
e5bd0d98 160
3d68eaf5 161The document structure is formed by sections that must be defined consistently.
e5bd0d98 162
3d68eaf5 163The document can contain plain text, lists, tables, code snippets, images, math, etc.
164Any specific text elements can be introduced by Markdown language tags or by usual HTML tags.
e5bd0d98 165
3d68eaf5 166The table of contents, page numbers (in PDF), and figure numbers (in PDF) are generated automatically.
e5bd0d98 167
3d68eaf5 168@subsection OCCT_DM_SECTION_A_1 Headers and hierarchic document structure
e5bd0d98 169
3d68eaf5 170Headers of different levels can be specified with the following tags:
3f812249 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.
3d68eaf5 174
175For example:
e5bd0d98 176
177@verbatim
3d68eaf5 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
e5bd0d98 181@endverbatim
182
3d68eaf5 183Please, 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.
184For example, *occt_ocaf* for sections in Open CASCADE Application Framework manual.
e5bd0d98 185
3d68eaf5 186The 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.
e5bd0d98 187
3d68eaf5 188The 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.
e5bd0d98 189
3d68eaf5 190If 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.
e5bd0d98 191
3d68eaf5 192The section hierarchy is limited to three levels and further levels cannot be presented in the Table of Contents.
e5bd0d98 193
3d68eaf5 194However, the fourth and fifth level headers can be tagged with <i>####</i> and <i>#####</i> correspondingly.
e5bd0d98 195
3d68eaf5 196It 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.
e5bd0d98 197
198@subsection OCCT_DM_SECTION_A_2 Plain Text
199
3d68eaf5 200A plain text is organized in paragraphs, separated by empty lines in MarkDown source.
201The 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
203To insert special symbols, like \< , \> or \\, prepend them with \\ character: \\\<, \\\>, \\\\, etc.
204To 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
e5bd0d98 208
209@subsection OCCT_DM_SECTION_A_3 Lists
210
211To create a bulleted list, start each line with a hyphen or an asterisk,
212followed by a space. List items can be nested. This code:
213
214@verbatim
79d580f2 215* Bullet 1
216* Bullet 2
217 - Bullet 2a
218 - Bullet 2b
219* Bullet 3
e5bd0d98 220@endverbatim
221
79d580f2 222produces this list:
e5bd0d98 223
79d580f2 224* Bullet 1
225* Bullet 2
226 * Bullet 2a
227 * Bullet 2b
228* Bullet 3
e5bd0d98 229
79d580f2 230To create a numbered list, start each line with number and a period,
231then a space. Numbered lists can also be nested. Thus this code
e5bd0d98 232
233@verbatim
79d580f2 2341. List item 1
235 1. Sub-item 1
236 2. Sub-item 2
2372. List item 2
3d68eaf5 2384. List item 3
e5bd0d98 239@endverbatim
240
79d580f2 241produces this list:
e5bd0d98 242
79d580f2 2431. List item 1
244 1. Sub-item 1
245 2. Sub-item 2
2462. List item 2
2473. List item 3
e5bd0d98 248
3d68eaf5 249**Note** that numbers of list items in the output are generated so they do not necessarily follow the numbering of source items.
250
251In 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.
252The use of explicit HTML tags \<ol\>\</ol\> and \<li\>\</li\> can help in this case.
253
79d580f2 254Each list item can contain several paragraphs of text; these paragraphs must
255have the same indentation as text after bullet or number in the numbered list
256item (otherwise numbering will be broken).
257
258Code blocks can be inserted as paragraphs with additional indentation
259(4 spaces more). Note that fenced code blocks do not work within numbered lists
260and their use may cause numeration to be reset.
261
262
3d68eaf5 263Example of a complex nested list:
79d580f2 264
2651. 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
2832. List item 2
284
e5bd0d98 285
286@subsection OCCT_DM_SECTION_A_4 Tables
287
288A table consists of a header line, a separator line, and at least one row line.
289Table columns are separated by the pipe (|) character. The following example:
290
291@verbatim
292First Header | Second Header
293------------- | -------------
294Content Cell | Content Cell
295Content Cell | Content Cell
296@endverbatim
297
298 will produce the following table:
299
300First Header | Second Header
301------------ | -------------
302Content Cell | Content Cell
303Content Cell | Content Cell
304
305Column 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
314which will looks as follows:
315
316| Right | Center | Left |
317| ----: | :----: | :---- |
318| 10 | 10 | 10 |
319| 1000 | 1000 | 1000 |
320
3d68eaf5 321Note that each table row should be contained in one line of text; complex tables can be created using HTML tags.
79d580f2 322
e5bd0d98 323@subsection OCCT_DM_SECTION_A_5 Code Blocks
324
3d68eaf5 325Paragraphs indented with 4 or more spaces are considered as code fragments and rendered using Courier font.
326Example:
327
328 This line is indented by 4 spaces and rendered as a code block.
329
e5bd0d98 330A fenced code block does not require indentation, and is defined by a pair of "fence lines".
331Such line consists of 3 or more tilde (~) characters on a line.
3d68eaf5 332The end of the block should have the same number of tildes.
333Thus it is strongly advised to use only three or four tildes.
e5bd0d98 334
335By default the output is the same as for a normal code block.
336To highlight the code, the developer has to indicate the typical file extension,
337which corresponds to the programming language, after the opening fence.
338For highlighting according to the C++ language, for instance, write the following code (the curly braces and dot are optional):
339
340@verbatim
3d68eaf5 341~~~{.cpp}
bb27b807 342int func(int a,int b) { return a*b; }
3d68eaf5 343~~~
e5bd0d98 344@endverbatim
345
346which will produce:
3d68eaf5 347~~~{.cpp}
bb27b807 348int func(int a,int b) { return a*b; }
3d68eaf5 349~~~
e5bd0d98 350
3d68eaf5 351Smaller code blocks can be inserted by wrapping with tags <i>\@code</i> and <i>\@endcode</i>.
bb27b807 352
3d68eaf5 353Verbatim content (same as code but without syntax highlighting) can be inserted by wrapping with tags <i>\@verbatim</i> and <i>\@endverbatim</i>.
e5bd0d98 354
355@subsection OCCT_DM_SECTION_A_6 References
356
3d68eaf5 357To insert a reference to a website, it is sufficient to write an URL.
358For example: http://en.wikipedia.org
e5bd0d98 359
3d68eaf5 360To insert a reference to a document or its subsection, use command <i>\@ref</i> followed by the document or section tag name.
361For instance, @code @ref OCCT_DM_SECTION_A @endcode will be rendered as @ref OCCT_DM_SECTION_A.
e5bd0d98 362
3d68eaf5 363Note that links between documents will not work in PDF output if each document is generated independently.
364Hence 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.
365For instance: @code @ref occt_modat_1 "Geometry Utilities" @endcode will be rendered as @ref occt_modat_1 "Geometry Utilities".
e5bd0d98 366
367@subsection OCCT_DM_SECTION_A_7 Images
368
3d68eaf5 369For inserting images into the document use the command <i>\@figure</i>, as follows:
bb27b807 370
bb27b807 371@verbatim
3d68eaf5 372 @figure{/relative/path/to/image/image_file_name.png,"Image caption"}
bb27b807 373@endverbatim
374
3d68eaf5 375The first argument is a path to the image file, relative to the *dox* folder.
376The supported formats for images are PNG, JPG, and SVG.
377The file extension must be lowercase and correspond to the file format.
378The image file name should have no dots except for the one before extension (names with more than one dot confuse **pdflatex**).
379
380The second argument is optional, it defines the caption for the image to be inserted.
381The caption argument, if given, should be quoted, even if it is a single word.
382Captions are included below the image; in PDF output the images with caption are numbered automatically.
383
384Example:
bb27b807 385
e5bd0d98 386@verbatim
3d68eaf5 387 @figure{/dev_guides/documentation/images/documentation_test_image.svg,"Test SVG image"}
e5bd0d98 388@endverbatim
389
3d68eaf5 390is rendered as:
391
d6b4d3d0 392@figure{/dev_guides/documentation/images/documentation_test_image.svg,"Test SVG image",320}
3d68eaf5 393
394We recommend using **Inkscape** for creation and edition of vector graphics.
395The graphics created in MS Word Draw and some other vector editors can be copy-pasted to Inkscape and saved as SVG images.
396
397Note 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
399Note 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
e5bd0d98 401@verbatim
d6b4d3d0 402 @image html /relative/path/to/image/occ_logo_for_html.png
403 @image latex /relative/path/to/image/occ_logo_for_pdf.png
e5bd0d98 404@endverbatim
405
e5bd0d98 406@subsection OCCT_DM_SECTION_A_8 Table Of Contents
407
3d68eaf5 408Use \@tableofcontents tag to get the table of contents at the beginning of the document.
409
410Actually, it is not strictly necessary now because TreeView option for HTML is used.
e5bd0d98 411The TOC in the PDF document will be generated automatically.
412
413@subsection OCCT_DM_SECTION_A_9 Formulas
414
e8181411 415Formulas within MarkDown documents can be defined using LaTeX syntax.
e5bd0d98 416
417Equations can be written by several ways:
418
4191.Unnumbered displayed formulas that are centered on a separate line.
420These formulas should be put between \@f\[ and \@f\] tags. An example:
421
422@verbatim
dd21889e 423@f[
e5bd0d98 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|
dd21889e 432@f]
e5bd0d98 433@endverbatim
434
435gives 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
3d68eaf5 4482.Formulas can also be put between @verbatim \begin{align} @endverbatim and @verbatim \end{align} @endverbatim tags.
e5bd0d98 449
3d68eaf5 450 For example:
451
e5bd0d98 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
4773.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$
d6b4d3d0 484