From: dpasukhi Date: Mon, 16 Dec 2024 16:17:31 +0000 (+0000) Subject: Documentation - Move `gendoc` to `adm` directory #199 X-Git-Tag: V7_9_0_beta1~92 X-Git-Url: http://git.dev.opencascade.org/gitweb/?a=commitdiff_plain;h=73ec4a59da7483bba3cd4aa71bb9d07772a6ff39;p=occt.git Documentation - Move `gendoc` to `adm` directory #199 Update documentation paths and improve generation instructions --- diff --git a/.github/workflows/build-docs.yml b/.github/workflows/build-docs.yml index b7b7b6caa8..27896aa987 100644 --- a/.github/workflows/build-docs.yml +++ b/.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 diff --git a/README.md b/README.md index a3275acbb3..71c546aa14 100644 --- a/README.md +++ b/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 diff --git a/adm/gendoc b/adm/gendoc new file mode 100644 index 0000000000..75f0f99e3c --- /dev/null +++ b/adm/gendoc @@ -0,0 +1,19 @@ +#!/bin/bash + +# Helper script to run generation of OCCT documentation on Linux. +# Running it requires that Tcl, Doxygen, and MikTex (for PDF generation) should be in the PATH + +anArgs=$* +anOldPath="$PATH" +anOldLd="$LD_LIBRARY_PATH" +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 + +tclsh "${aScriptPath}/start.tcl" gendoc $anArgs + +export PATH="$anOldPath" +export LD_LIBRARY_PATH="$anOldLd" +export DYLD_LIBRARY_PATH="$anOldDyLd" diff --git a/adm/gendoc.bat b/adm/gendoc.bat new file mode 100644 index 0000000000..bf8da09dd0 --- /dev/null +++ b/adm/gendoc.bat @@ -0,0 +1,23 @@ +@echo off + +rem Helper script to run generation of OCCT documentation on Windows. +rem Running it requires that Tcl, Doxygen, and MikTex (for PDF generation) +rem should be in the PATH + +SET "OLD_PATH=%PATH%" + +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% %~dp0start.tcl gendoc %* +) else ( + echo "Error. %TCL_EXEC% is not found. Please update PATH variable" +) + +SET "PATH=%OLD_PATH%" diff --git a/dox/build/build_documentation/building_documentation.md b/dox/build/build_documentation/building_documentation.md index 8784a2e247..994be6e949 100644 --- a/dox/build/build_documentation/building_documentation.md +++ b/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: diff --git a/dox/contribution/documentation/documentation.md b/dox/contribution/documentation/documentation.md index 3c8b768365..b7836d811b 100644 --- a/dox/contribution/documentation/documentation.md +++ b/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=|-ug=\] \[-v\] \[-s=\] \[-mathjax=\] diff --git a/gendoc b/gendoc deleted file mode 100755 index 2d77ea9fae..0000000000 --- a/gendoc +++ /dev/null @@ -1,19 +0,0 @@ -#!/bin/bash - -# Helper script to run generation of OCCT documentation on Linux. -# Running it requires that Tcl, Doxygen, and MikTex (for PDF generation) should be in the PATH - -anArgs=$* -anOldPath="$PATH" -anOldLd="$LD_LIBRARY_PATH" -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 - -tclsh "${aScriptPath}/adm/start.tcl" gendoc $anArgs - -export PATH="$anOldPath" -export LD_LIBRARY_PATH="$anOldLd" -export DYLD_LIBRARY_PATH="$anOldDyLd" diff --git a/gendoc.bat b/gendoc.bat deleted file mode 100644 index 0fc61a4fd0..0000000000 --- a/gendoc.bat +++ /dev/null @@ -1,23 +0,0 @@ -@echo off - -rem Helper script to run generation of OCCT documentation on Windows. -rem Running it requires that Tcl, Doxygen, and MikTex (for PDF generation) -rem should be in the PATH - -SET "OLD_PATH=%PATH%" - -if exist "%~dp0env.bat" ( - call "%~dp0env.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 %* -) else ( - echo "Error. %TCL_EXEC% is not found. Please update PATH variable" -) - -SET "PATH=%OLD_PATH%"