1 Documentation System {#dev_guides__documentation}
6 @section OCCT_DM_SECTION_1 Introduction
8 This document provides practical guidenes for generation and editing of OCCT user documentation.
10 @section OCCT_DM_SECTION_2 Prerequisites
13 Version 8.5 or 8.6: http://www.tcl.tk/software/tcltk/download.html
16 Version 1.8.4 or above: http://www.stack.nl/~dimitri/doxygen/download.html
18 <b>MathJax</b> (used for rendering math formulas in browser).
19 See \ref OCCT_DM_SECTION_A_9 paragraph for more detailed description.
20 The latest version: http://www.mathjax.org/download/
22 <b>MiKTeX</b> or equivalent tool (used for PDF document creation)
24 Latest version: http://miktex.org/download
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:
30 @image html /dev_guides/documentation/images/documentation_image002.png
31 @image latex /dev_guides/documentation/images/documentation_image002.png
33 If this option is set to "Yes", MiKTeX will download missing packages automatically.
35 @section OCCT_DM_SECTION_2_1 Documentation Generation
37 Run gendoc.bat from OCCT directory to generate all articles are defined in FILES.txt:
41 * -html : To generate HTML files (cannot be used with -pdf);
42 * -pdf : To generate PDF files (cannot be used with -html);
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;
45 * -h : Prints help message;
46 * -v : Specifies the Verbose mode (info on all script actions is shown).
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.
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.
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).
59 devs_guid/documentation/documentation.md
62 where documentation .md is name of article and devs_guid/documentation/ is relative path of it
64 * use this name with -m option in the generation process:
67 % gendoc.bat -html -m=devs_guid/documentation/documentation.md
70 Multiple files are separated with comma:
73 % gendoc.bat -html -m=MD_FILE_1,MD_FILE_2
76 To sepcify a article name with -l option, use quotes to prevent incorrect interpretation of whitespaces:
79 % gendoc.bat -pdf -m=MD_FILE_1 -l="Label of MD_FILE_1 document"
82 @section OCCT_DM_SECTION_3 Documentation Conventions
84 This section contains information about conventions in the field of OCCT documentation file format,
85 structure of documentation directories, etc.
87 @subsection OCCT_DM_SECTION_3_1 File Format
89 It is proposed to use MarkDown file format for easy maintainance of generic text documents.
90 The MarkDown files have a "*.md" extension and are based on rules desribed in
91 @htmlonly <a href="#OCCT_DM_SECTION_A">Document Syntax</a> @endhtmlonly section.
93 @subsection OCCT_DM_SECTION_3_2 Directory Structure
95 @image html /dev_guides/documentation/images/documentation_image001.png
96 @image latex /dev_guides/documentation/images/documentation_image001.png
98 Every separate article has own folder if images are used in it. These images
99 are stored into "images" subfolder.
101 If you want to use the same image for several articles, you can place the one into "dox/resources" folder.
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
106 @image html /dev_guides/snv/images/snv_image001.svg
109 Result of generation of the documentation is:
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.
115 @section OCCT_DM_SECTION_4 Adding a New Article
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
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
120 the own folder of the article and subfolder in it for images. For instance
121 */dox/dev_guides/svn/ - for svn.md file
122 */dox/dev_guides/svn/images/ - for images
124 - Update dox/FILES.txt to add relative path to svn.md. For instance
126 dev_guides/snv/svn.md
129 **Note**: the place of the relative path to an article is connected with the place
130 into treeview of html version.
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.
136 @section OCCT_DOC_SECTION_5 Additional Resources
138 More information about OCCT can be found at http://www.opencascade.org
140 The information on formula syntax can be found at:
141 http://en.wikipedia.org/wiki/Help:Displaying_a_formula
143 More information on MarkDown and Doxygen syntax can be found at:
144 http://www.stack.nl/~dimitri/doxygen/manual
146 @section OCCT_DM_SECTION_A Appendix 1: Document Syntax
148 Each OCCT document file in *.md format has a simple structure.
151 | Content type | Obligation |
152 | :---------------- | :-------------------: |
161 | Page numbers | M (auto generation) |
162 | Table of contents | M (auto generation) |
169 @subsection OCCT_DM_SECTION_A_1 Text Caption (a header)
171 headings of different levels can be specified with the following code:
183 and with the following code:
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:
200 @section Section_Name Section Header
201 @subsection SubSection_Name SubSection Header
202 @subsubsection SubSubSection_Name SubSubSection Header
205 @subsection OCCT_DM_SECTION_A_2 Plain Text
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**.
212 @subsection OCCT_DM_SECTION_A_3 Lists
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:
233 To create a numbered list, start each line with number and a period, then a space. Thus this code
247 It is recommended to indent lists with 2 spaces.
249 @subsection OCCT_DM_SECTION_A_4 Tables
251 A table consists of a header line, a separator line, and at least one row line.
252 Table columns are separated by the pipe (|) character. The following example:
255 First Header | Second Header
256 ------------- | -------------
257 Content Cell | Content Cell
258 Content Cell | Content Cell
261 will produce the following table:
263 First Header | Second Header
264 ------------ | -------------
265 Content Cell | Content Cell
266 Content Cell | Content Cell
268 Column alignment can be controlled via one or two colons at the header separator line:
271 | Right | Center | Left |
272 | ----: | :----: | :---- |
274 | 1000 | 1000 | 1000 |
277 which will looks as follows:
279 | Right | Center | Left |
280 | ----: | :----: | :---- |
282 | 1000 | 1000 | 1000 |
284 @subsection OCCT_DM_SECTION_A_5 Code Blocks
286 It is recommended to indent a code lines with 4 spaces.
287 A fenced code block does not require indentation, and is defined by a pair of "fence lines".
288 Such line consists of 3 or more tilde (~) characters on a line.
289 The end of the block should have the same number of tildes. Here is an example:
291 ~~~~~~~~~~~~~~~~~~~~~~~
292 a one-line code block
293 ~~~~~~~~~~~~~~~~~~~~~~~
295 By default the output is the same as for a normal code block.
296 To highlight the code, the developer has to indicate the typical file extension,
297 which corresponds to the programming language, after the opening fence.
298 For highlighting according to the C++ language, for instance, write the following code (the curly braces and dot are optional):
301 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~{.cpp}
302 int func(int a,int b) { return a*b; }
303 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
307 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~{.cpp}
308 int func(int a,int b) { return a*b; }
309 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
311 Verbatim content can be written by using framing \@verbatim \@endverbatim . For instance
317 @subsection OCCT_DM_SECTION_A_6 References
319 To insert a reference to a website, it is proposed to write a URL. For example: http://en.wikipedia.org
320 To insert a reference to another part of the same document, the developer can write:
324 <a href="#OCCT_DOC_SECTION_5">Doxygen Configuration file</a>
328 to get a link to paragraph : @htmlonly <a href="#OCCT_DOC_SECTION_5">Doxygen configuration</a> @endhtmlonly
330 @subsection OCCT_DM_SECTION_A_7 Images
332 To insert image into document the developer can write the following code(in Doxygen-style):
334 ![alt-caption](relative/path/to/image/image001.svg "Image Caption")
337 This code tells Doxygen to insert a picture right in the place this code was written. Like this:
339 ![](/resources/occ_logo.png "OCCT logo")
342 ![](/resources/occ_logo.png "OCCT logo")
344 @subsection OCCT_DM_SECTION_A_8 Table Of Contents
346 To get the table of contents at the beginning of the document, write \@tableofcontents tag.
347 But it is not needed now because TreeView option for HTML is used.
348 The TOC in the PDF document will be generated automatically.
350 @subsection OCCT_DM_SECTION_A_9 Formulas
352 Formulas within documents will be generated using MathJax tool.
354 A developer has to specify these parameters in Doxyfile to enable support of MathJax in Doxygen:
357 MATHJAX_FORMAT = HTML-CSS
358 MATHJAX_RELPATH = http://cdn.mathjax.org/mathjax/latest
359 MATHJAX_EXTENSIONS = TeX/AMSmath TeX/AMSsymbols
361 To use MathJax tool with the HTML page, it's \<head\> block has to contain
363 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~{.html}
364 <script type="text/x-mathjax-config">
366 tex2jax: {inlineMath: [["$","$"],["\\(","\\)"]]},
371 <script type="text/javascript"
372 src="http://cdn.mathjax.org/mathjax/latest/MathJax.js?config=TeX-AMS-MML_HTMLorMML">
374 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
376 First script configures MathJax to understand separator types and to left allign formulas.
377 The second script inserts reference to MathJax tool.
378 This tool will always be used when the HTML output will be shown.
380 Equations can be written by several ways:
382 1.Unnumbered displayed formulas that are centered on a separate line.
383 These formulas should be put between \@f\[ and \@f\] tags. An example:
387 |I_2|=\left| \int_{0}^T \psi(t)
391 \frac{d\theta}{k(\theta,t)}
392 \int_{a}^\theta c(\xi)u_t(\xi,t)\,d\xi
398 gives the following result:
401 |I_2|=\left| \int_{0}^T \psi(t)
405 \frac{d\theta}{k(\theta,t)}
406 \int_{a}^\theta c(\xi)u_t(\xi,t)\,d\xi
411 2.Formulas can also be put between @verbatim \begin{align} @endverbatim and @verbatim \end{align} @endverbatim tags. An example:
415 \dot{x} & = \sigma(y-x) \\
416 \dot{y} & = \rho x - y - xz \\
417 \dot{z} & = -\beta z + xy
421 gives the following result:
424 \dot{x} & = \sigma(y-x) \\
425 \dot{y} & = \rho x - y - xz \\
426 \dot{z} & = -\beta z + xy
432 \dot{x} & = \sigma(y-x) \\
433 \dot{y} & = \rho x - y - xz \\
434 \dot{z} & = -\beta z + xy
438 3.Inline formulas can be specified using this syntax:
441 @f$ \sqrt{3x-1}+(1+x)^2 @f$
444 that leads to the following result: @f$ \sqrt{3x-1}+(1+x)^2 @f$