OpenCascade/occt
1
0
Fork 0
mirror of https://git.dev.opencascade.org/repos/occt.git synced 2025-08-14 13:30:48 +03:00
Code Activity

0028654: Existed tool (gendoc) for generation documentation does not take into account size of images.

Browse Source 
The parameter defining image width has been added to all figures to improve their layout in PDF documents and tweaked depending on the nature of each image.
Additionally, some minor changes improving image and text layout have been introduced.

Remove temporary added possibility for setting image width automatically for generation of pdf documentation.
This commit is contained in:
ysn
2017-06-02 11:55:34 +03:00
committed by bugmaster
parent 26e0b3353c
commit d6b4d3d0d5
20 changed files with 478 additions and 562 deletions
Download Patch File Download Diff File Expand all files Collapse all files

5
dox/dev_guides/contribution_workflow/contribution_workflow.md
View File

@@ -35,7 +35,7 @@ According to his access level, the user can participate in the issue handling pr
@subsection occt_contribution_workflow_general General scheme
<center>
@figure{OCCT_ContributionWorkflow_V3_image001.svg, "Standard life cycle of an issue"}
@figure{OCCT_ContributionWorkflow_V3_image001.svg,"Standard life cycle of an issue",360}
</center>
@subsection occt_contribution_workflow_issue Issue registration
@@ -280,7 +280,7 @@ Each change is integrated as a single commit without preserving the history of c
This is done to have the master branch history plain and clean.
The following picture illustrates the process:
@figure{OCCT_ContributionWorkflow_V3_image002.png, "Integration of several branches"}
@figure{OCCT_ContributionWorkflow_V3_image002.png,"Integration of several branches",420}
The new integration branch is tested against possible regressions that might appear due to interference between separate changes.
When the tests are OK, the integration branch is pushed as the new master to the official repository.
@@ -461,3 +461,4 @@ The category corresponds to the component of OCCT where the issue is found:
| Suspended | The issue is postponed (for Acknowledged status). |
| Documentation updated | The documentation has been updated to resolve a misunderstanding causing the issue. |
| Won’t fix | It is decided to keep the existing behavior. |

21
dox/dev_guides/documentation/documentation.md
View File

@@ -30,7 +30,7 @@ You can use *custom.bat* file to add necessary paths to the *PATH* variable.
Note that in the process of PDF generation MiKTeX may need some packages not installed by default.
We recommend setting option "Install missing packages on-the-fly" to "Ask me first" (default) during MiKTeX installation:
@figure{/dev_guides/documentation/images/documentation_miktex.png}
@figure{/dev_guides/documentation/images/documentation_miktex.png,"",320}
On the first run of **pdflatex** it will open a dialog window prompting for installation of missing packages.
Follow the instructions to proceed (define proxy settings if needed, select a mirror site to download from, etc.).
@@ -102,7 +102,7 @@ The MarkDown files have a <i>*.md</i> extension and are based on rules described
@subsection OCCT_DM_SECTION_3_2 Directory Structure
@figure{/dev_guides/documentation/images/documentation_folders.png}
@figure{/dev_guides/documentation/images/documentation_folders.png,"",160}
Each document has its own folder if there are any images used in it. These images are stored in *images* subfolder.
@@ -112,7 +112,7 @@ If you want to use the same image for several documents, you can place it in *do
@verbatim
@figure{/dev_guides/documentation/images/documentation_test_image.svg}
@figure{/dev_guides/documentation/images/documentation_test_image.svg,"",420}
@endverbatim
@@ -140,13 +140,13 @@ dev_guides/svn/svn.md
@section OCCT_DOC_SECTION_5 Additional Resources
More information about OCCT can be found at http://www.opencascade.com and http://dev.opencascade.org sites.
More information about OCCT can be found at http://www.opencascade.com and <br> http://dev.opencascade.org sites.
The information on formula syntax can be found at:
The information on formula syntax can be found at: <br>
http://en.wikipedia.org/wiki/Help:Displaying_a_formula
More information on MarkDown and Doxygen syntax can be found at:
More information on MarkDown and Doxygen syntax can be found at: <br>
http://www.stack.nl/~dimitri/doxygen/manual
@section OCCT_DM_SECTION_A Appendix 1: Document Syntax
@@ -389,7 +389,7 @@ Example:
is rendered as:
@figure{/dev_guides/documentation/images/documentation_test_image.svg,"Test SVG image"}
@figure{/dev_guides/documentation/images/documentation_test_image.svg,"Test SVG image",320}
We recommend using **Inkscape** for creation and edition of vector graphics.
The graphics created in MS Word Draw and some other vector editors can be copy-pasted to Inkscape and saved as SVG images.
@@ -399,11 +399,10 @@ Note that the image that will be included in documentation is the whole page of
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:
@verbatim
@figure{/relative/path/to/image/occ_logo.png, "OCC logo"}
@image html /relative/path/to/image/occ_logo_for_html.png
@image latex /relative/path/to/image/occ_logo_for_pdf.png
@endverbatim
@figure{/resources/occ_logo.png, "OCC logo"}
@subsection OCCT_DM_SECTION_A_8 Table Of Contents
Use \@tableofcontents tag to get the table of contents at the beginning of the document.
@@ -482,4 +481,4 @@ gives the following result:
@endverbatim
that leads to the following result: @f$ \sqrt{3x-1}+(1+x)^2 @f$

37
dox/dev_guides/git_guide/git_guide.md
View File

@@ -124,7 +124,7 @@ The official repository contains:
TortoiseGit integrates into Windows Explorer, thus it is possible to use context menu in Windows Explorer to access its functionality:
@figure{OCCT_GitGuide_V2_image005.png}
@figure{OCCT_GitGuide_V2_image005.png,"",100}
@@ -137,7 +137,7 @@ The official repository contains:
Select Git->Config to add your user name and Email address to the local <i>.gitconfig</i> file
@figure{OCCT_GitGuide_V2_image006.png}
@figure{OCCT_GitGuide_V2_image006.png,"",320}
@subsection occt_gitguide_2_2 Linux platform
@@ -188,7 +188,7 @@ The official repository contains:
To generate the key with this client, run **Puttygen** (e.g. from Start menu -> TortoiseGit -> Puttygen),
then click **Generate** and move mouse cursor over the blank area until the key is generated.
@figure{OCCT_GitGuide_V2_image007.png, "Putty key generator"}
@figure{OCCT_GitGuide_V2_image007.png,"Putty key generator",320}
After the key is generated, you will see GUI controls to define the public key comment
and / or specify the password for the private key protection.
@@ -292,7 +292,7 @@ Click **Save** to input the key to the system.
* In TortoiseGit: create a new folder, open it and right-click in the Explorer window, then choose **Git Clone** in the context menu:
@figure{OCCT_GitGuide_V2_image009.png}
@figure{OCCT_GitGuide_V2_image009.png,"",320}
If you have chosen Putty as SSH client during TortoiseGit installation, check the **Load Putty Key** option and specify the location of the private key file saved by PuttyGen (see 3.2.1). This shall be done for the first time only.
@@ -317,7 +317,7 @@ In TortoiseGit:
* Right-click in the Explorer window, then choose **Git Create Branch**.
* Select **Base On** Branch *remotes/origin/master*.
@figure{OCCT_GitGuide_V2_image012.png}
@figure{OCCT_GitGuide_V2_image012.png,"",320}
Check option **Switch to new branch** if you are going to start working with the newly created branch immediately.
@@ -332,7 +332,7 @@ In TortoiseGit:
In TortoiseGit: right-click in the explorer window and select in the context menu **TortoiseGit** -> **Switch/Checkout**.
@figure{OCCT_GitGuide_V2_image013.png}
@figure{OCCT_GitGuide_V2_image013.png,"",320}
Note that in order to work with the branch locally you need to set option
**Create new branch** when you checkout the branch from the remote repository for the first time.
@@ -366,7 +366,7 @@ In TortoiseGit:
* In TortoiseGit: right-click in the explorer window and select in the context menu <b>Git Commit -> CR…</b>:
@figure{OCCT_GitGuide_V2_image014.png}
@figure{OCCT_GitGuide_V2_image014.png,"",320}
Unstaged files will be shown if you check the option ‘Show Unversioned Files’.
Double-click on each modified file to see the changes to be committed (as a difference vs. the base version).
@@ -384,13 +384,13 @@ In TortoiseGit:
* In TortoiseGit: right-click in the explorer window and select in the context menu, TortoiseGit -> **Push**
@figure{OCCT_GitGuide_V2_image015.png}
@figure{OCCT_GitGuide_V2_image015.png,"",320}
Note that Git forbids pushing a branch if the corresponding remote branch already exists and has some changes, which are not in the history of your local branch. This may happen in different situations:
* You have amended the last commit which is already in the remote repository. If you are sure that nobody else uses your branch, push again with **Force** option.
* You have rebased your branch, so that now it is completely different from the branch in the remote repository. In this case, push it under a different name (add a suffix):
@figure{OCCT_GitGuide_V2_image016.png}
@figure{OCCT_GitGuide_V2_image016.png,"",320}
Then remove the original remote branch so that other people recognize that it has been replaced by the new one. For that, select TortoiseGit -> **Push** again, select an empty line for your local branch name,
and enter the name of the branch to be removed in **Remote** field:
@@ -410,7 +410,7 @@ Note that Git forbids pushing a branch if the corresponding remote branch alread
* In TortoiseGit: right-click in the explorer window and select in the context menu **TortoiseGit** -> **Fetch**. Check in **Prune** check-box.
@figure{OCCT_GitGuide_V2_image018.png}
@figure{OCCT_GitGuide_V2_image018.png,"",320}
If the branch you are working with has been changed in the remote repository, use Git command *pull* to get the remote changes and merge them with your local branch.
@@ -423,7 +423,7 @@ Note that Git forbids pushing a branch if the corresponding remote branch alread
* In TortoiseGit: right-click in the explorer window and select in the context menu **TortoiseGit** -> **Pull**.
@figure{OCCT_GitGuide_V2_image019.png}
@figure{OCCT_GitGuide_V2_image019.png,"",320}
Note that the local branches of your repository are the primary place, where your changes are stored until they get integrated to the official version of OCCT (master branch). The branches submitted to official repository are for collaborative work, review, and integration -- that repository should not be used for long-term storage of incomplete changes.
@@ -436,7 +436,7 @@ Remove the local branches that you do not need any more. Note that you cannot de
* In TortoiseGit: right-click in the explorer window and select in the context menu **TortoiseGit** -> **Git Show Log**.
@figure{OCCT_GitGuide_V2_image020.png}
@figure{OCCT_GitGuide_V2_image020.png,"",420}
Select **All branches** check-box to view all branches.
Right-click on the branch you want to delete and select **Delete** item in the context menu.
@@ -450,13 +450,13 @@ If you have a fix made on a previous version of OCCT, perform the following sequ
* Find a tag or a commit corresponding to this version in the Git history log of the master branch.
* Create a branch basing on this tag or commit. In TortoiseGit history log: right-click on the base commit, then select **Create branch at this version**.
@figure{OCCT_GitGuide_V2_image021.png}
@figure{OCCT_GitGuide_V2_image021.png,"",320}
* Check option **Switch to the new branch** to start working within the new branch immediately, or switch to it separately afterwards.
* Put your fix in the working copy, build and check that it works, then commit to the branch.
* Rebase the branch on the current master. In TortoiseGit: right-click on the working directory, choose **TortoiseGit** -> **Rebase**, select *remotes/origin/master* as UpStream revision, and click **Start**:
@figure{OCCT_GitGuide_V2_image022.png}
@figure{OCCT_GitGuide_V2_image022.png,"",320}
Note that you can get some conflicts during rebase. To resolve them, double-click on each conflicted file (highlighted by red in the file list) to open visual merge tool. Switch between conflicting fragments by red arrows, and for each one decide if the code of one or both conflicting versions is to be taken.
@@ -473,16 +473,16 @@ To rebase your branch into a single commit, you need to do the following:
* In TortoiseGit history log, select a branch to rebase on <i>(remotes/origin/master)</i> and in the context menu choose **Rebase “CR12345” onto this**.
* In the **Rebase** dialog, check **Squash All**. You can also change the order of commits and define for each commit whether it should be kept (**Pick**), edited, or just skipped.
@figure{OCCT_GitGuide_V2_image023.png}
@figure{OCCT_GitGuide_V2_image023.png,"",320}
* Click **Start**.
* The process will stop if a conflict is detected. In that case, find files with status **Conflicted** in the list (marked by red), and double-click on them to resolve the conflict. When all conflicts are resolved, click **Continue**.
@figure{OCCT_GitGuide_V2_image024.png}
@figure{OCCT_GitGuide_V2_image024.png,"",320}
* At the end of the process, edit the final commit message (it should start from the issue ID and a description from Mantis in the first line, followed by a summary of actual changes), and click **Commit**.
@figure{OCCT_GitGuide_V2_image025.png}
@figure{OCCT_GitGuide_V2_image025.png,"",320}
@section occt_gitguide_5 Work with repository: Reviewer operations
@@ -508,5 +508,6 @@ To rebase your branch into a single commit, you need to do the following:
* To review commits one-by-one, select each commit in the log. The list of changed files is shown at the bottom of the window; double-click on the file will open visual compare tool.
* To review all changes made in the branch at once, or to compare two arbitrary revisions, select the corresponding commits in the log (e.g. the last commit in the branch and the branching point), ight-click for the context menu, and choose **Compare revisions**.
@figure{OCCT_GitGuide_V2_image026.png}
@figure{OCCT_GitGuide_V2_image026.png,"",320}

3
dox/dev_guides/tests/tests.md
View File

@@ -242,7 +242,7 @@ The names *begin, end, data, parse.rules, grids.list* and *cases.list* are reser
General layout of test scripts is shown in Figure 1.
@figure{/dev_guides/tests/images/tests_image001.png, "Layout of tests folder"}
@figure{/dev_guides/tests/images/tests_image001.png,"Layout of tests folder",400}
@subsection testmanual_2_2 Test Groups
@@ -1406,3 +1406,4 @@ Use options <i>-tol_\* </i> for that.
~~~~~
checktrinfo result -defl 1 -tol_abs_defl 0.001
~~~~~