dox/dev_guides/documentation/documentation.md

   1  Documentation  {#dev_guides__documentation}
   2 =================
   3
   4 @section  OCCT_DM_SECTION_1 Introduction
   5
   6 This document provides practical guidenes for generation and editing of OCCT user documentation.
   7
   8 @section  OCCT_DM_SECTION_2 Prerequisites
   9
  10 <b>Tcl/Tk</b>
  11 The lates version: http://www.tcl.tk/software/tcltk/download.html
  12
  13 <b>Doxygen</b> ( >= 1.8.4 )
  14 The latest version: http://www.stack.nl/~dimitri/doxygen/download.html
  15
  16 <b>MathJax</b> (used for rendering math formulas in browser). Download it for local installation or use the MathJax Content Delivery Network.  \(read
  17 @htmlonly <a href="#OCCT_DM_SECTION_A_9">Formulas</a> @endhtmlonly paragraph for more detailed description\).
  18 The latest version: http://www.mathjax.org/download/
  19
  20 <b>MiKTeX</b> or equivalent tool (used for PDF document creation)
  21 Latest version: http://miktex.org/download
  22
  23 **Note**: to generate pdf documentation with MiKTeX you should execute gen.bat with MiKTeX environment
  24 (e.g. into MiKTeX command promt)
  25
  26 @section OCCT_DM_SECTION_2_1 Documentation Generation
  27
  28 Run gendoc.bat from OCCT directory to generate all articles are defined in FILES.txt:
  29
  30 gendoc.bat options:
  31
  32   * -html                : To generate HTML files (cannot be used with -pdf);
  33   * -pdf                 : To generate PDF files (cannot be used with -html);
  34   * -m=<modules_list>    : Specifies list of articles to generate. If it is not specified, all files, mentioned in FILES.txt are processed;
  35   * -l=<document_name>   : Specifies the article caption for a single document;
  36   * -h                   : Prints help message;
  37   * -v                   : Specifies the Verbose mode (info on all script actions is shown).
  38
  39 If you run the command without arguments (like example above) it will generate HTML documentation
  40 for all articles are defined into FILES.txt.
  41
  42 **Note**: the generation process generates PDF files for each article,
  43 but in html case it generates common Html page with references to the ones.
  44
  45 For generation of specific article you need:
  46   * have it's name with relative path (from \%OCCDIR\%/dox/ to the file) contained in FILES.txt
  47   (is located into \%OCCDIR\%/dox/ directory).
  48
  49 @verbatim
  50 devs_guid/documentation/documentation.md
  51 @endverbatim
  52
  53 where documentation .md is name of article and devs_guid/documentation/ is relative path of it
  54
  55   * use this name with -m option in the generation process:
  56
  57 @verbatim
  58 % gen.bat -html -m=devs_guid/documentation/documentation.md
  59 @endverbatim
  60
  61 Multiple files are separated with comma:
  62
  63 @verbatim
  64 % gen.bat -html -m=MD_FILE_1,MD_FILE_2
  65 @endverbatim
  66
  67 To sepcify a article name with -l option, use tcl list to prevent whitespaces incorrect interpretation:
  68
  69 @verbatim
  70 % gen.bat -pdf -m=MD_FILE_1 -l=[list MD File 1 Label]
  71 @endverbatim
  72
  73 @section  OCCT_DM_SECTION_3 Documentation Conventions
  74
  75 This section contains information about conventions in the field of OCCT documentation file format,
  76 structure of documentation directories, etc.
  77
  78 @subsection  OCCT_DM_SECTION_3_1 File Format
  79
  80 It is proposed to use MarkDown file format for easy maintainance of generic text documents.
  81 The MarkDown files have a "*.md" extension and are based on rules desribed in
  82 @htmlonly <a href="#OCCT_DM_SECTION_A">Document Syntax</a> @endhtmlonly section.
  83
  84 @subsection  OCCT_DM_SECTION_3_2 Directory Structure
  85
  86 @image html /dev_guides/documentation/images/documentation_image001.png
  87 @image latex /dev_guides/documentation/images/documentation_image001.png
  88
  89 Every separate article has own folder if images are used in it. These images
  90 are stored into "images" subfolder.
  91
  92 If you want to use the same image for several articles, you can place the one into "dox/resources" folder.
  93
  94 **Note**: Every article can use any image that is used by others articles. To avoid incorrect image
  95 displaying, use relative path to the image (starting from dox folder). For instance
  96 @verbatim
  97 @image html /dev_guides/snv/images/snv_image001.svg
  98 @endverbatim
  99
 100 Result of generation of the documentation is:
 101
 102 %OCCT_DIR% / doc         - a folder for generated articles;
 103             * html/             - a directory for generated HTML pages;
 104             * pdf/              - a directory for generated PDF files.
 105
 106 @section  OCCT_DM_SECTION_4 Adding a New Article
 107
 108  - Place a new article into folder that is chosen taking into account the place of the article
 109 at the hierarchy of the documentation. For instance the article about "using SVN working with OCCT
 110 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
 111 the own folder of the article and subfolder in it for images. For instance
 112 */dox/dev_guides/svn/ - for svn.md file
 113 */dox/dev_guides/svn/images/ - for images
 114
 115  - Update dox/FILES.txt to add relative path to svn.md. For instance
 116 @verbatim
 117 dev_guides/snv/svn.md
 118 @endverbatim
 119
 120 **Note**: the place of the relative path to an article is connected with the place
 121 into treeview of html version.
 122
 123
 124 Note, that you should specify a file tag, not the document name.
 125 See <a href="#OCCT_DM_SECTION_A_1">Header section</a> for details.
 126
 127 @section  OCCT_DOC_SECTION_5 Additional Resources
 128
 129 More information about OCCT can be found at http://www.opencascade.org
 130
 131 The information on formula syntax can be found at:
 132 http://en.wikipedia.org/wiki/Help:Displaying_a_formula
 133
 134 More information on MarkDown and Doxygen syntax can be found at:
 135 http://www.stack.nl/~dimitri/doxygen/manual