From 73ec4a59da7483bba3cd4aa71bb9d07772a6ff39 Mon Sep 17 00:00:00 2001 From: dpasukhi Date: Mon, 16 Dec 2024 16:17:31 +0000 Subject: [PATCH] Documentation - Move `gendoc` to `adm` directory #199 Update documentation paths and improve generation instructions --- .github/workflows/build-docs.yml | 4 ++++ README.md | 11 ++++++----- gendoc => adm/gendoc | 4 ++-- gendoc.bat => adm/gendoc.bat | 6 +++--- .../build_documentation/building_documentation.md | 2 +- dox/contribution/documentation/documentation.md | 2 +- 6 files changed, 17 insertions(+), 12 deletions(-) rename gendoc => adm/gendoc (79%) mode change 100755 => 100644 rename gendoc.bat => adm/gendoc.bat (81%) 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/gendoc b/adm/gendoc old mode 100755 new mode 100644 similarity index 79% rename from gendoc rename to adm/gendoc index 2d77ea9fae..75f0f99e3c --- a/gendoc +++ b/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" diff --git a/gendoc.bat b/adm/gendoc.bat similarity index 81% rename from gendoc.bat rename to adm/gendoc.bat index 0fc61a4fd0..bf8da09dd0 100644 --- a/gendoc.bat +++ b/adm/gendoc.bat @@ -6,8 +6,8 @@ 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" @@ -15,7 +15,7 @@ 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" ) 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=\]