From 13658aed3df59584ec599934539de0b7a4b339d7 Mon Sep 17 00:00:00 2001 From: christophKaiser <64251870+christophKaiser@users.noreply.github.com> Date: Fri, 8 Apr 2022 20:45:56 +0200 Subject: [PATCH 1/7] Adjust Doxygen-option in CMakeLists.txt --- CMakeLists.txt | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/CMakeLists.txt b/CMakeLists.txt index d4894e601..0e25e300d 100644 --- a/CMakeLists.txt +++ b/CMakeLists.txt @@ -321,7 +321,7 @@ endforeach() #------------------------------------------------------------------------------ # DOXYGEN. #------------------------------------------------------------------------------ -Option(DOXYGEN_GENERATE_DOCUMENTATION "Build documentation for TUM OpenInfraPlatform." OFF) +Option(DOXYGEN_GENERATE_DOCUMENTATION "Build documentation for TUM OpenInfraPlatform." ON) if(DOXYGEN_GENERATE_DOCUMENTATION) From 448c267d82a7f52b0efb510a558ce55ad5ffcf13 Mon Sep 17 00:00:00 2001 From: christophKaiser <64251870+christophKaiser@users.noreply.github.com> Date: Sun, 10 Apr 2022 16:00:32 +0200 Subject: [PATCH 2/7] Revert "Adjust Doxygen-option in CMakeLists.txt" This reverts commit 13658aed3df59584ec599934539de0b7a4b339d7. --- CMakeLists.txt | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/CMakeLists.txt b/CMakeLists.txt index 0e25e300d..d4894e601 100644 --- a/CMakeLists.txt +++ b/CMakeLists.txt @@ -321,7 +321,7 @@ endforeach() #------------------------------------------------------------------------------ # DOXYGEN. #------------------------------------------------------------------------------ -Option(DOXYGEN_GENERATE_DOCUMENTATION "Build documentation for TUM OpenInfraPlatform." ON) +Option(DOXYGEN_GENERATE_DOCUMENTATION "Build documentation for TUM OpenInfraPlatform." OFF) if(DOXYGEN_GENERATE_DOCUMENTATION) From e9f3f06f549617603468638997b84bab05e1021d Mon Sep 17 00:00:00 2001 From: christophKaiser <64251870+christophKaiser@users.noreply.github.com> Date: Sun, 10 Apr 2022 16:09:39 +0200 Subject: [PATCH 3/7] Typo --- Documentation/markdown/DoxygenHelp.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/Documentation/markdown/DoxygenHelp.md b/Documentation/markdown/DoxygenHelp.md index f267a2eda..25e57dcfe 100644 --- a/Documentation/markdown/DoxygenHelp.md +++ b/Documentation/markdown/DoxygenHelp.md @@ -54,7 +54,7 @@ http://www.doxygen.nl/manual/index.html Important: when adding settings in CMake, always use DOXYGEN_ before the standard doxygen tag, e.g. the doxygen tag "PROJECT_BRIEF" has to be "DOXYGEN_PROJECT_BRIEF" in the ConfigureDoxygen.cmake file. ## Building the documentation -In Visual studio, build "OpenInfraPlatform.GenerateDocumentation". This target can be found in Visual Studio under OpenInfraPlatform/Commands. +In Visual Studio, build "OpenInfraPlatform.GenerateDocumentation". This target can be found in Visual Studio under OpenInfraPlatform/Commands. If "DOXYGEN_OPTIONAL_AUTO_OPEN_DOCUMENTATION" was selected in the CMake GUI, the landing pages of the documentation will be opened automatically if the build succeeded. Otherwise, the documentation has to be opened manually. In your build directory under Doxymentation/html you will find something called “index.html”. Clicking on this file will open the landing page of the HTML documentation browser. From faba21a3c82fa94080079741808719958eafa598 Mon Sep 17 00:00:00 2001 From: christophKaiser <64251870+christophKaiser@users.noreply.github.com> Date: Sun, 10 Apr 2022 16:23:13 +0200 Subject: [PATCH 4/7] Adjustment of description according to current state (ON -> OFF) --- Documentation/markdown/DoxygenHelp.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/Documentation/markdown/DoxygenHelp.md b/Documentation/markdown/DoxygenHelp.md index 25e57dcfe..957be3b3e 100644 --- a/Documentation/markdown/DoxygenHelp.md +++ b/Documentation/markdown/DoxygenHelp.md @@ -21,7 +21,7 @@ Refer to the [doxygen manual](http://www.doxygen.nl/manual) for everything else. ### Top-level CMakelists.txt -If `DOXYGEN_GENERATE_DOCUMENTATION` is checked in the CMake GUI (default = ON), CMake will try to find the doxygen and dot executables in `C/thirdparty`. Additionally, a command that builds the documentation will be added to the solution. +If `DOXYGEN_GENERATE_DOCUMENTATION` is checked in the CMake GUI (default = OFF), CMake will try to find the doxygen and dot executables in `C/thirdparty`. Additionally, a command that builds the documentation will be added to the solution. Additionally, the following options can be selected: - `DOXYGEN_INCLUDE_COMMENTED_ONLY` (default = ON): If selected, only the documentation for explicitly commented entities will be generated. Otherwise, doxygen will assume that all entities are documented, even if there is no documentation available. From d8d3afa7365c684c80e107c9b9800ecd1cdd9976 Mon Sep 17 00:00:00 2001 From: christophKaiser <64251870+christophKaiser@users.noreply.github.com> Date: Sun, 10 Apr 2022 16:24:04 +0200 Subject: [PATCH 5/7] Added description how to enable doxygen --- Documentation/markdown/DoxygenHelp.md | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/Documentation/markdown/DoxygenHelp.md b/Documentation/markdown/DoxygenHelp.md index 957be3b3e..5d7138897 100644 --- a/Documentation/markdown/DoxygenHelp.md +++ b/Documentation/markdown/DoxygenHelp.md @@ -19,6 +19,10 @@ Refer to the [doxygen manual](http://www.doxygen.nl/manual) for everything else. ## Doxygen settings in CMake +By default, doxygen is disabled. +To enable doxygen, search for the `DOXYGEN_GENERATE_DOCUMENTATION` option in CMake and set the check box. +After *Generate* in CMake, the Visual Studio Solution Explorer includes the project "OpenInfraPlatform.GenerateDocumentation". + ### Top-level CMakelists.txt If `DOXYGEN_GENERATE_DOCUMENTATION` is checked in the CMake GUI (default = OFF), CMake will try to find the doxygen and dot executables in `C/thirdparty`. Additionally, a command that builds the documentation will be added to the solution. From 03e664bc3ac68a0716b6071c305dcb96f8f79537 Mon Sep 17 00:00:00 2001 From: christophKaiser <64251870+christophKaiser@users.noreply.github.com> Date: Sun, 10 Apr 2022 16:26:06 +0200 Subject: [PATCH 6/7] Added missing syntax of code highlighting --- Documentation/markdown/DoxygenHelp.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/Documentation/markdown/DoxygenHelp.md b/Documentation/markdown/DoxygenHelp.md index 5d7138897..e83c7b2fe 100644 --- a/Documentation/markdown/DoxygenHelp.md +++ b/Documentation/markdown/DoxygenHelp.md @@ -30,16 +30,16 @@ If `DOXYGEN_GENERATE_DOCUMENTATION` is checked in the CMake GUI (default = OFF), Additionally, the following options can be selected: - `DOXYGEN_INCLUDE_COMMENTED_ONLY` (default = ON): If selected, only the documentation for explicitly commented entities will be generated. Otherwise, doxygen will assume that all entities are documented, even if there is no documentation available. - `DOXYGEN_INCLUDE_INTERNAL` (default = OFF): If selected, this will include all comments preceded by "\internal". These are comments intended for developers only. So if the generated documentation is intended for external users, this option should not be selected. -- DOXYGEN_INCLUDE_EARLYBINDING (default = OFF): If selected (... and already built), this will include the selected IFC schemas in the documentation. Otherwise, the schemas will not be included in the documentation, but this does not influence the selection of IFC schemas (see EARLYBINDING_ tags in CMake GUI). -- DOXYGEN_AUTO_OPEN_DOCUMENTATION (default = ON): If selected, the landing page of the documentation will automatically open. If not selected, you will have to find and open the generated documentation manually (see section below on building the documentation). +- `DOXYGEN_INCLUDE_EARLYBINDING` (default = OFF): If selected (... and already built), this will include the selected IFC schemas in the documentation. Otherwise, the schemas will not be included in the documentation, but this does not influence the selection of IFC schemas (see EARLYBINDING_ tags in CMake GUI). +- `DOXYGEN_AUTO_OPEN_DOCUMENTATION` (default = ON): If selected, the landing page of the documentation will automatically open. If not selected, you will have to find and open the generated documentation manually (see section below on building the documentation). ### ConfigureDoxygen.cmake -If DOXYGEN_GENERATE_DOCUMENTATION is selected in CMake, CMake will include ConfigureDoxygen.cmake. This file includes all settings for the generation of doxygen documentation for the Open Infra Platform project. Changes to documentation settings should be made here. doxygen_add_docs() creates the GenerateDocumentation target. The up-to-date version of the file can be found here: +If `DOXYGEN_GENERATE_DOCUMENTATION` is selected in CMake, CMake will include ConfigureDoxygen.cmake. This file includes all settings for the generation of doxygen documentation for the Open Infra Platform project. Changes to documentation settings should be made here. doxygen_add_docs() creates the GenerateDocumentation target. The up-to-date version of the file can be found here: See [file](../../cmake/ConfigureDoxygen.cmake) #### ToDos. -The DOXYGEN_EXCLUDE_PATTERNS tag used in ConfigureDoxygen.cmake is one that is more likely to be required to change. +The `DOXYGEN_EXCLUDE_PATTERNS` tag used in ConfigureDoxygen.cmake is one that is more likely to be required to change. It excludes certain source code directories or files from the documentation. In this project, the following directories including the following patterns are currently excluded: - CurrentlyExcluded - cmake From aae0c685a71b305f3f9906acea90d7d02283cafe Mon Sep 17 00:00:00 2001 From: christophKaiser <64251870+christophKaiser@users.noreply.github.com> Date: Sun, 10 Apr 2022 16:32:36 +0200 Subject: [PATCH 7/7] Added optional hint in the SetupHelp --- Documentation/markdown/SetupHelp.md | 1 + 1 file changed, 1 insertion(+) diff --git a/Documentation/markdown/SetupHelp.md b/Documentation/markdown/SetupHelp.md index 6754b805b..5f20b49a6 100644 --- a/Documentation/markdown/SetupHelp.md +++ b/Documentation/markdown/SetupHelp.md @@ -177,6 +177,7 @@ Build the project **OpenInfraPlatform.GenerateDocumentation** within *Commands* *NOTE:* This step may take quite some time. Read more about Doxygen in our [guidelines](./DoxygenHelp.md). +*NOTE:* Doxygen is disabled by default. See the guidelines for a description how to enable Doxygen. Please consult our [CMake options documentation](./CMakeOptions.md) for different options available for customizing the doxygeneration.