Documentation - Move gendoc to adm directory #199

Update documentation paths and improve generation instructions

.github/workflows/build-docs.yml

@@ -8,6 +8,9 @@ on:
   push:
     branches:
       - 'master'
+  pull_request:
+    branches:
+      - '**'
 
 jobs:
   build:
@@ -26,6 +29,7 @@ jobs:
     - name: Build documentation
       run: |
         set PATH=%PATH%;C:\Program Files\doxygen\bin;C:\Program Files\Graphviz\bin;C:\Program Files\doxygen
+        cd adm
         bash gendoc -refman
       shell: cmd
 

README.md

@@ -28,22 +28,23 @@ You can also find OCCT pre-installed on your system or install it from packages
 
 Documentation is available at the following links:
 - [Latest version](https://dev.opencascade.org/doc/overview)
-- [Version 7.7](https://dev.opencascade.org/doc/occt-7.7.0/overview)
+- [Version 7.8](https://dev.opencascade.org/doc/occt-7.8.0/overview)
 
 Documentation can be part of the package. To preview documentation as part of the package, open the file `doc/html/index.html` to browse HTML documentation.
 
 If HTML documentation is not available in your package, you can:
 
-- **Generate it from sources:** You need to have Tcl and Doxygen 1.8.4 (or above) installed on your system and accessible in your environment (check the environment variable PATH). Use the batch file `gendoc.bat` on Windows or the Bash script `gendoc` on Linux or OS X to (re)generate documentation.
-- **Read documentation in source plain text (Markdown) format** found in the subfolder `dox`.
+- **Generate it from sources:** You need to have Tcl and Doxygen 1.8.4 (or above) installed on your system and accessible in your environment (check the environment variable PATH). Use the batch file `adm/gendoc.bat` on Windows or the Bash script `adm/gendoc` on Linux or OS X to (re)generate documentation.
+- **Generate together with sources:** You need to have CMake and 1.8.4 (or above) installed on your system. Enable `BUILD_DOC_Overview` CMake parameter and set the path to Doxygen `3RDPARTY_DOXYGEN_EXECUTABLE`. Then build ALL or only `Overview`.
+- **Read documentation in source plain text (Markdown) format** found in the subfolder `dox` or [GitHub Wiki](https://github.com/Open-Cascade-SAS/OCCT/wiki).
 
-See `dox/dev_guides/documentation/documentation.md` or [Building Documentation](https://dev.opencascade.org/doc/occt-7.7.0/overview/html/build_upgrade__building_documentation.html) for details.
+See `dox/dev_guides/documentation/documentation.md` or [Building Documentation](https://dev.opencascade.org/doc/occt-7.8.0/overview/html/build_upgrade__building_documentation.html) for details.
 
 ## Building
 
 In most cases, you need to rebuild OCCT on your platform (OS, compiler) before using it in your project to ensure binary compatibility.
 
-Consult the file `dox/dev_guides/building/building.md` or [Building OCCT](https://dev.opencascade.org/doc/overview/html/build_upgrade__building_occt.html) for instructions on building OCCT from sources on supported platforms.
+Consult the file `dox/dev_guides/building/building.md` or [Building OCCT](https://dev.opencascade.org/doc/overview/html/build_upgrade__building_occt.html) or [Building OCCT Wiki](https://github.com/Open-Cascade-SAS/OCCT/wiki/build_upgrade) for instructions on building OCCT from sources on supported platforms.
 
 ## Version
 

gendoc → adm/gendoc

@@ -10,9 +10,9 @@ anOldDyLd="$DYLD_LIBRARY_PATH"
 
 # go to the script directory
 aScriptPath=${BASH_SOURCE%/*}; if [ -d "${aScriptPath}" ]; then cd "$aScriptPath"; fi; aScriptPath="$PWD";
-if [ -e "${aScriptPath}/env.sh" ]; then source "${aScriptPath}/env.sh"; fi
+if [ -e "${aScriptPath}/../env.sh" ]; then source "${aScriptPath}/../env.sh"; fi
 
-tclsh "${aScriptPath}/adm/start.tcl" gendoc $anArgs
+tclsh "${aScriptPath}/start.tcl" gendoc $anArgs
 
 export PATH="$anOldPath"
 export LD_LIBRARY_PATH="$anOldLd"

gendoc.bat → adm/gendoc.bat

@@ -6,16 +6,16 @@ rem should be in the PATH
 
 SET "OLD_PATH=%PATH%"
 
-if exist "%~dp0env.bat" (
-  call "%~dp0env.bat"
+if exist "%~dp0../env.bat" (
+  call "%~dp0../env.bat"
 )
 
 set "TCL_EXEC=tclsh.exe"
 
 for %%X in (%TCL_EXEC%) do (set TCL_FOUND=%%~$PATH:X)
 
 if defined TCL_FOUND (
-  %TCL_EXEC% %~dp0adm/start.tcl gendoc %*
+  %TCL_EXEC% %~dp0start.tcl gendoc %*
 ) else (
   echo "Error. %TCL_EXEC% is not found. Please update PATH variable"
 )

dox/build/build_documentation/building_documentation.md

@@ -4,7 +4,7 @@
 To generate HTML documentation from sources contained in *dox* subdirectory, 
 you need to have Tcl and Doxygen 1.8.5 (or above) installed on your system.
 
-Use script **gendoc** (batch file on Windows, shell script on Linux / Mac OSX) to generate documentation.
+Use script **gendoc** (batch file on Windows, shell script on Linux / Mac OSX) located in `adm` directory to generate documentation.
 
 To generate Overview documentation:
 

dox/contribution/documentation/documentation.md

@@ -59,7 +59,7 @@ See \ref OCCT_DM_SECTION_A_9 for more details on inserting mathematical expressi
 
 @section OCCT_DM_SECTION_2_1 Documentation Generation
 
-Run command *gendoc* from command prompt (with OCCT directory as current one) to generate OCCT documentation.
+Run command *gendoc* from command prompt (located in `adm` directory) to generate OCCT documentation.
 The synopsis is:
 
     gendoc \[-h\] {-refman|-overview} \[-html|-pdf|-chm\] \[-m=<list of modules>|-ug=<list of docs>\] \[-v\] \[-s=<search_mode>\] \[-mathjax=<path>\]