mirror of
https://git.dev.opencascade.org/repos/occt.git
synced 2025-08-04 13:13:25 +03:00
0024269: Content of occt documentation should be formated
building subsection introduced; wok moved to dev guides section;
Requirements and Installation sections were interchanged;
some Unicode characters removed from .md files; \DeclareUnicodeCharacter{00A0}{ } instruction added into refman file
images insertion rolled back to dual html,latex insertion; mainpage now is processed (index.tex);
surplus part of overview has been removed
foundation_classes.md and technical_overview.md updated;
Reviewed step, tobj, xde and partly iges; Corrections in other guides.
Overview installation and requirements changes updated
This commit is contained in:
ysn
bugmaster
@@ -20,6 +20,9 @@ The latest version: http://www.mathjax.org/download/
|
||||
<b>MiKTeX</b> or equivalent tool (used for PDF document creation)
|
||||
Latest version: http://miktex.org/download
|
||||
|
||||
**Note**: to generate pdf documentation with MiKTeX you should execute gen.bat with MiKTeX environment
|
||||
(e.g. into MiKTeX command promt)
|
||||
|
||||
@section OCCT_DM_SECTION_2_1 Documentation Generation
|
||||
|
||||
Run gendoc.bat from OCCT directory to generate all articles are defined in FILES.txt:
|
||||
@@ -80,7 +83,8 @@ The MarkDown files have a "*.md" extension and are based on rules desribed in
|
||||
|
||||
@subsection OCCT_DM_SECTION_3_2 Directory Structure
|
||||
|
||||
|
||||
@image html /dev_guides/documentation/images/documentation_image001.png
|
||||
@image latex /dev_guides/documentation/images/documentation_image001.png
|
||||
|
||||
Every separate article has own folder if images are used in it. These images
|
||||
are stored into "images" subfolder.
|
||||
@@ -90,7 +94,7 @@ If you want to use the same image for several articles, you can place the one in
|
||||
**Note**: Every article can use any image that is used by others articles. To avoid incorrect image
|
||||
displaying, use relative path to the image (starting from dox folder). For instance
|
||||
@verbatim
|
||||
|
||||
@image html /dev_guides/snv/images/snv_image001.svg
|
||||
@endverbatim
|
||||
|
||||
Result of generation of the documentation is:
|
||||
@@ -103,14 +107,14 @@ Result of generation of the documentation is:
|
||||
|
||||
- Place a new article into folder that is chosen taking into account the place of the article
|
||||
at the hierarchy of the documentation. For instance the article about "using SVN working with OCCT
|
||||
source code" (svn.md - the file of the article) might be placed into /dox/devs_guide/ . If the article has images then you may create
|
||||
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
|
||||
the own folder of the article and subfolder in it for images. For instance
|
||||
*/dox/devs_guide/svn/ - for svn.md file
|
||||
*/dox/devs_guide/svn/images/ - for images
|
||||
*/dox/dev_guides/svn/ - for svn.md file
|
||||
*/dox/dev_guides/svn/images/ - for images
|
||||
|
||||
- Update dox/FILES.txt to add relative path to svn.md. For instance
|
||||
@verbatim
|
||||
devs_guide/snv/svn.md
|
||||
dev_guides/snv/svn.md
|
||||
@endverbatim
|
||||
|
||||
**Note**: the place of the relative path to an article is connected with the place
|
||||
@@ -129,403 +133,3 @@ http://en.wikipedia.org/wiki/Help:Displaying_a_formula
|
||||
|
||||
More information on MarkDown and Doxygen syntax can be found at:
|
||||
http://www.stack.nl/~dimitri/doxygen/manual
|
||||
|
||||
|
||||
@section OCCT_DM_SECTION_A Appendix 1: Document Syntax
|
||||
|
||||
Each OCCT document file in *.md format has a simple structure.
|
||||
It can contain:
|
||||
|
||||
| Content type | Obligation |
|
||||
| :---------------- | :-------------------: |
|
||||
| Header | M |
|
||||
| Footer | M |
|
||||
| Plain text | O |
|
||||
| List | O |
|
||||
| Table | O |
|
||||
| Code | O |
|
||||
| Formula | O |
|
||||
| Image | O |
|
||||
| Page numbers | M (auto generation) |
|
||||
| Table of contents | M (auto generation) |
|
||||
|
||||
The legend:
|
||||
|
||||
* M is for Mandatory
|
||||
* O is for Optional
|
||||
|
||||
@subsection OCCT_DM_SECTION_A_1 Text Caption (a header)
|
||||
|
||||
headings of different levels can be specified with the following code:
|
||||
|
||||
@verbatim
|
||||
Header 1 {#header1}
|
||||
=======
|
||||
@endverbatim
|
||||
|
||||
to get
|
||||
|
||||
Header 1
|
||||
=========
|
||||
|
||||
and with the following code:
|
||||
|
||||
@verbatim
|
||||
Header 2 {#header2}
|
||||
--------
|
||||
@endverbatim
|
||||
|
||||
to get
|
||||
|
||||
Header 2
|
||||
---------
|
||||
|
||||
Where a word in curly braces is a MarkDown-style reference, which can be used in table of contents.
|
||||
If you would like to have the table of contents, it is recommended to use \@section,
|
||||
\@subsection and \@subsubsection pages instead of MarkDown headers as follows:
|
||||
|
||||
@verbatim
|
||||
@section Section_Name Section Header
|
||||
@subsection SubSection_Name SubSection Header
|
||||
@subsubsection SubSubSection_Name SubSubSection Header
|
||||
@endverbatim
|
||||
|
||||
@subsection OCCT_DM_SECTION_A_2 Plain Text
|
||||
|
||||
Plain text is a text in a notepad-like format. To insert special symbols,
|
||||
like \< , \> or \\, prepend them with \\ character: \\\<, \\\>, \\\\
|
||||
To emphasize some words, write one pair of asterisks ( * ) or underscores ( _ ) across the word
|
||||
to make it *italic* and two pairs of these symbols to make a word **Bold**.
|
||||
|
||||
@subsection OCCT_DM_SECTION_A_3 Lists
|
||||
|
||||
To create a bulleted list, start each line with a hyphen or an asterisk,
|
||||
followed by a space. List items can be nested. This code:
|
||||
|
||||
@verbatim
|
||||
* Bullet 1
|
||||
* Bullet 2
|
||||
* Bullet 2a
|
||||
* Bullet 2b
|
||||
* Bullet 3
|
||||
@endverbatim
|
||||
|
||||
produces this list:
|
||||
|
||||
* Bullet 1
|
||||
* Bullet 2
|
||||
* Bullet 2a
|
||||
* Bullet 2b
|
||||
* Bullet 3
|
||||
|
||||
To create a numbered list, start each line with number and a period, then a space. Thus this code
|
||||
|
||||
@verbatim
|
||||
1. ListItem_1
|
||||
2. ListItem_2
|
||||
3. ListItem_3
|
||||
@endverbatim
|
||||
|
||||
produces this list:
|
||||
|
||||
1. ListItem_1
|
||||
2. ListItem_2
|
||||
3. ListItem_3
|
||||
|
||||
It is recommended to indent lists with 2 spaces.
|
||||
|
||||
@subsection OCCT_DM_SECTION_A_4 Tables
|
||||
|
||||
A table consists of a header line, a separator line, and at least one row line.
|
||||
Table columns are separated by the pipe (|) character. The following example:
|
||||
|
||||
@verbatim
|
||||
First Header | Second Header
|
||||
------------- | -------------
|
||||
Content Cell | Content Cell
|
||||
Content Cell | Content Cell
|
||||
@endverbatim
|
||||
|
||||
will produce the following table:
|
||||
|
||||
First Header | Second Header
|
||||
------------ | -------------
|
||||
Content Cell | Content Cell
|
||||
Content Cell | Content Cell
|
||||
|
||||
Column alignment can be controlled via one or two colons at the header separator line:
|
||||
|
||||
@verbatim
|
||||
| Right | Center | Left |
|
||||
| ----: | :----: | :---- |
|
||||
| 10 | 10 | 10 |
|
||||
| 1000 | 1000 | 1000 |
|
||||
@endverbatim
|
||||
|
||||
which will looks as follows:
|
||||
|
||||
| Right | Center | Left |
|
||||
| ----: | :----: | :---- |
|
||||
| 10 | 10 | 10 |
|
||||
| 1000 | 1000 | 1000 |
|
||||
|
||||
@subsection OCCT_DM_SECTION_A_5 Code Blocks
|
||||
|
||||
It is recommended to indent a code lines with 4 spaces.
|
||||
A fenced code block does not require indentation, and is defined by a pair of "fence lines".
|
||||
Such line consists of 3 or more tilde (~) characters on a line.
|
||||
The end of the block should have the same number of tildes. Here is an example:
|
||||
|
||||
~~~~~~~~~~~~~~~~~~~~~~~
|
||||
a one-line code block
|
||||
~~~~~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
By default the output is the same as for a normal code block.
|
||||
To highlight the code, the developer has to indicate the typical file extension,
|
||||
which corresponds to the programming language, after the opening fence.
|
||||
For highlighting according to the C++ language, for instance, write the following code (the curly braces and dot are optional):
|
||||
|
||||
@verbatim
|
||||
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~{.cpp}
|
||||
int func(int a,int b) { return a*b; }
|
||||
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||
@endverbatim
|
||||
|
||||
which will produce:
|
||||
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~{.cpp}
|
||||
int func(int a,int b) { return a*b; }
|
||||
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
Verbatim content can be written by using framing \@verbatim \@endverbatim . For instance
|
||||
|
||||
@verbatim
|
||||
verbatim text
|
||||
@endverbatim
|
||||
|
||||
@subsection OCCT_DM_SECTION_A_6 References
|
||||
|
||||
To insert a reference to a website, it is proposed to write a URL. For example: http://en.wikipedia.org
|
||||
To insert a reference to another part of the same document, the developer can write:
|
||||
|
||||
@verbatim
|
||||
@htmlonly
|
||||
<a href="#OCCT_DOC_SECTION_5">Doxygen Configuration file</a>
|
||||
@endhtmlonly
|
||||
@endverbatim
|
||||
|
||||
to get a link to paragraph : @htmlonly <a href="#OCCT_DOC_SECTION_5">Doxygen configuration</a> @endhtmlonly
|
||||
|
||||
@subsection OCCT_DM_SECTION_A_7 Images
|
||||
|
||||
To insert image into document the developer can write the following code(in Doxygen-style):
|
||||
@verbatim
|
||||
|
||||
@endverbatim
|
||||
|
||||
This code tells Doxygen to insert a picture right in the place this code was written. Like this:
|
||||
@verbatim
|
||||
|
||||
@endverbatim
|
||||
|
||||
|
||||
|
||||
@subsection OCCT_DM_SECTION_A_8 Table Of Contents
|
||||
|
||||
To get the table of contents at the beginning of the document, write \@tableofcontents tag.
|
||||
But it is not needed now because TreeView option for HTML is used.
|
||||
The TOC in the PDF document will be generated automatically.
|
||||
|
||||
@subsection OCCT_DM_SECTION_A_9 Formulas
|
||||
|
||||
Formulas within documents will be generated using MathJax tool.
|
||||
|
||||
A developer has to specify these parameters in Doxyfile to enable support of MathJax in Doxygen:
|
||||
|
||||
USE_MATHJAX = YES
|
||||
MATHJAX_FORMAT = HTML-CSS
|
||||
MATHJAX_RELPATH = http://cdn.mathjax.org/mathjax/latest
|
||||
MATHJAX_EXTENSIONS = TeX/AMSmath TeX/AMSsymbols
|
||||
|
||||
To use MathJax tool with the HTML page, it's \<head\> block has to contain
|
||||
|
||||
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~{.html}
|
||||
<script type="text/x-mathjax-config">
|
||||
MathJax.Hub.Config({
|
||||
tex2jax: {inlineMath: [["$","$"],["\\(","\\)"]]},
|
||||
displayAlign: "left"
|
||||
});
|
||||
</script>
|
||||
|
||||
<script type="text/javascript"
|
||||
src="http://cdn.mathjax.org/mathjax/latest/MathJax.js?config=TeX-AMS-MML_HTMLorMML">
|
||||
</script>
|
||||
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
First script configures MathJax to understand separator types and to left allign formulas.
|
||||
The second script inserts reference to MathJax tool.
|
||||
This tool will always be used when the HTML output will be shown.
|
||||
|
||||
Equations can be written by several ways:
|
||||
|
||||
1.Unnumbered displayed formulas that are centered on a separate line.
|
||||
These formulas should be put between \@f\[ and \@f\] tags. An example:
|
||||
|
||||
@verbatim
|
||||
@f$[
|
||||
|I_2|=\left| \int_{0}^T \psi(t)
|
||||
\left\{
|
||||
u(a,t)-
|
||||
\int_{\gamma(t)}^a
|
||||
\frac{d\theta}{k(\theta,t)}
|
||||
\int_{a}^\theta c(\xi)u_t(\xi,t)\,d\xi
|
||||
\right\} dt
|
||||
\right|
|
||||
@f$]
|
||||
@endverbatim
|
||||
|
||||
gives the following result:
|
||||
|
||||
@f$
|
||||
|I_2|=\left| \int_{0}^T \psi(t)
|
||||
\left\{
|
||||
u(a,t)-
|
||||
\int_{\gamma(t)}^a
|
||||
\frac{d\theta}{k(\theta,t)}
|
||||
\int_{a}^\theta c(\xi)u_t(\xi,t)\,d\xi
|
||||
\right\} dt
|
||||
\right|
|
||||
@f$
|
||||
|
||||
2.Formulas can also be put between @verbatim \begin{align} @endverbatim and @verbatim \end{align} @endverbatim tags. An example:
|
||||
|
||||
@verbatim
|
||||
\begin{align}
|
||||
\dot{x} & = \sigma(y-x) \\
|
||||
\dot{y} & = \rho x - y - xz \\
|
||||
\dot{z} & = -\beta z + xy
|
||||
\end{align}
|
||||
@endverbatim
|
||||
|
||||
gives the following result:
|
||||
@latexonly
|
||||
\begin{align}
|
||||
\dot{x} & = \sigma(y-x) \\
|
||||
\dot{y} & = \rho x - y - xz \\
|
||||
\dot{z} & = -\beta z + xy
|
||||
\end{align}
|
||||
@endlatexonly
|
||||
|
||||
@htmlonly
|
||||
\begin{align}
|
||||
\dot{x} & = \sigma(y-x) \\
|
||||
\dot{y} & = \rho x - y - xz \\
|
||||
\dot{z} & = -\beta z + xy
|
||||
\end{align}
|
||||
@endhtmlonly
|
||||
|
||||
3.Inline formulas can be specified using this syntax:
|
||||
|
||||
@verbatim
|
||||
@f$ \sqrt{3x-1}+(1+x)^2 @f$
|
||||
@endverbatim
|
||||
|
||||
that leads to the following result: @f$ \sqrt{3x-1}+(1+x)^2 @f$
|
||||
|
||||
@section OCCT_DM_SECTION_B Appendix 2: Doxygen Configuration
|
||||
|
||||
@subsection OCCT_DM_SECTION_B_1 Doxygen Configuration File
|
||||
|
||||
To generate documentation from "source" *.md files a developer can use file OCCT.doxyfile,
|
||||
which is located in /docs directory of OCCT (more information can be found at @htmlonly
|
||||
<a href="#OCCT_DM_SECTION_X_X_X">Directory Structure</a> @endhtmlonly paragraph)
|
||||
or create his own configuration file, called "Doxyfile". The configuration file may look as follows:
|
||||
|
||||
@verbatim
|
||||
DOXYFILE_ENCODING = UTF-8
|
||||
PROJECT_NAME = "OCCT User's Guides"
|
||||
PROJECT_NUMBER = 1.0.1
|
||||
PROJECT_LOGO = "D:/OS/OCCT/docs/OCCT_logo.png"
|
||||
OUTPUT_LANGUAGE = English
|
||||
TAB_SIZE = 4
|
||||
MARKDOWN_SUPPORT = YES
|
||||
AUTOLINK_SUPPORT = NO
|
||||
SHOW_FILES = NO
|
||||
WARNINGS = YES
|
||||
WARN_IF_UNDOCUMENTED = YES
|
||||
WARN_IF_DOC_ERROR = YES
|
||||
WARN_NO_PARAMDOC = NO
|
||||
WARN_FORMAT = "$file:$line: $text"
|
||||
INPUT = "D:/OS/OCCT/docs/"
|
||||
INPUT_ENCODING = UTF-8
|
||||
FILE_PATTERNS = *.md
|
||||
RECURSIVE = YES
|
||||
IMAGE_PATH = tmp
|
||||
GENERATE_HTML = YES
|
||||
SEARCHENGINE = NO
|
||||
HTML_OUTPUT = html
|
||||
HTML_FILE_EXTENSION = .html
|
||||
HTML_HEADER = "static/header.html"
|
||||
HTML_FOOTER = "static/footer.html"
|
||||
HTML_STYLESHEET = "static/general.css"
|
||||
HTML_EXTRA_STYLESHEET = "static/styles.css"
|
||||
HTML_COLORSTYLE_HUE = 220
|
||||
HTML_COLORSTYLE_SAT = 100
|
||||
HTML_COLORSTYLE_GAMMA = 80
|
||||
HTML_TIMESTAMP = YES
|
||||
HTML_DYNAMIC_SECTIONS = NO
|
||||
HTML_INDEX_NUM_ENTRIES = 100
|
||||
GENERATE_LATEX = YES
|
||||
GENERATE_RTF = YES
|
||||
@endverbatim
|
||||
|
||||
@subsection OCCT_DM_SECTION_B_2 Doxygen Output Customization
|
||||
|
||||
The customization of the output files, produced by Doxygen, can be made by using different Doxyfile parameters,
|
||||
like HTML_COLORSTYLE_SAT, which specifies one of HSV color component of HTML page header, and also by using DoxygenLayout xml file.
|
||||
A developer can use default file from /docs directory or generate his own with doxygen -l command. It may looks as follows:
|
||||
|
||||
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~{.xml}
|
||||
<doxygenlayout version="1.0">
|
||||
<!-- Generated by doxygen 1.8.3.1 -->
|
||||
<!-- Navigation index tabs for HTML output -->
|
||||
<navindex>
|
||||
<tab type="mainpage" visible="yes" title="Introduction"/>
|
||||
<tab type="pages" visible="yes" title="Documents" intro=
|
||||
"This section contains links to all OCCT documents that are available at the moment"/>
|
||||
<tab type="modules" visible="no" title="" intro=""/>
|
||||
<tab type="namespaces" visible="no" title="">
|
||||
<tab type="namespacelist" visible="no" title="" intro=""/>
|
||||
<tab type="namespacemembers" visible="no" title="" intro=""/>
|
||||
</tab>
|
||||
<tab type="classes" visible="no" title="">
|
||||
<tab type="classlist" visible="no" title="" intro=""/>
|
||||
<tab type="classindex" visible="$ALPHABETICAL_INDEX" title=""/>
|
||||
<tab type="hierarchy" visible="no" title="" intro=""/>
|
||||
<tab type="classmembers" visible="no" title="" intro=""/>
|
||||
</tab>
|
||||
<tab type="files" visible="yes" title="Files">
|
||||
<tab type="filelist" visible="yes" title="" intro=""/>
|
||||
<tab type="globals" visible="yes" title="" intro=""/>
|
||||
</tab>
|
||||
<tab type="examples" visible="no" title="" intro=""/>
|
||||
</navindex>
|
||||
...
|
||||
</doxygenlayout>
|
||||
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
The tag \<tab\> specifies tabs which appear at the head of each html page. For the OCCT user documentation
|
||||
"mainpage" and "pages" tabs are usually needed and their visible parameter should always be "yes".
|
||||
The visibility of other tabs should be set to "no".
|
||||
|
||||
Developers can find more information about Doxygen configuration in the help file
|
||||
or at http://www.stack.nl/~dimitri/doxygen/manual/
|
||||
|
||||
@subsection OCCT_DM_SECTION_B_3 Doxywizard Usage
|
||||
|
||||
The easiest way of applying and modification of Doxyfile is to use a Doxywizard application,
|
||||
which is usually a part of the Doxygen tool. To apply a configuration file, the developer should
|
||||
select "Open..." item of the File menu or press Ctrl + O. Modification of Doxyfile can be made
|
||||
using "Wizard" or "Expert" tabs of Doxywizard application.
|
||||
|
||||
Developers can find more information about Doxywizard usage in the help file or at
|
||||
http://www.stack.nl/~dimitri/doxygen/manual/doxywizard_usage.html.
|
||||
|
||||
Reference in New Issue
Block a user