Added DILIGENT_BUILD_DOCS option to enable DiligentDocs CMake target

Author: TheMostDiligent

CMakeLists.txt

@@ -14,6 +14,7 @@ project(DiligentEngine)
 option(DILIGENT_BUILD_TOOLS "Build DiligentTools module" ON)
 option(DILIGENT_BUILD_FX "Build DiligentFX module" ON)
 option(DILIGENT_BUILD_SAMPLES "Build DiligentSamples module" ON)
+option(DILIGENT_BUILD_DOCS "Build documentation" OFF)
 
 add_subdirectory(DiligentCore)
 if(EXISTS "${CMAKE_CURRENT_SOURCE_DIR}/DiligentCorePro")
@@ -47,6 +48,10 @@ if(${DILIGENT_BUILD_SAMPLES})
     add_subdirectory(DiligentSamples)
 endif()
 
+if(${DILIGENT_BUILD_DOCS})
+    add_subdirectory(Doc)
+endif()
+
 if(TARGET GLTFViewer)
     set_property(DIRECTORY PROPERTY VS_STARTUP_PROJECT GLTFViewer)
 elseif(TARGET Asteroids)

Doc/CMakeLists.txt

@@ -0,0 +1,12 @@
+cmake_minimum_required (VERSION 3.10)
+
+set(DOXYGEN_CONFIG_FILE "${CMAKE_CURRENT_SOURCE_DIR}/doxygen.cfg")
+set(MD_PAGES_SCRIPT "${CMAKE_CURRENT_SOURCE_DIR}/md_pages.py")
+set(PAGES_DOX "${CMAKE_CURRENT_SOURCE_DIR}/pages.dox")
+
+add_custom_target(DiligentDocs
+    WORKING_DIRECTORY "${CMAKE_CURRENT_SOURCE_DIR}/.." # Need to run in the root of the repo
+    COMMAND python "${MD_PAGES_SCRIPT}" "${PAGES_DOX}"
+    COMMAND doxygen "${DOXYGEN_CONFIG_FILE}"
+    COMMENT "Building documentation..."
+)

Doc/README.md

@@ -0,0 +1,27 @@
+# Building Documentation
+
+To build the documentation, install [Doxygen](https://www.doxygen.nl).
+Check the required version in the [GitHub Action file](https://github.com/DiligentGraphics/github-action/blob/master/install-doxygen/action.yml).
+
+Then, from the **root** of the repository, run the following commands:
+
+**1. Generate the Markdown pages list**
+
+By default, Doxygen lists all Markdown files in a flat, arbitrary order, which can look messy and isn't
+very user-friendly. Use the script below to organize the Markdown files into a tree structure and generate
+the `Doc/pages.dox` file:
+
+```bash
+python Doc/md_pages.py Doc/pages.dox
+```
+
+**2. Build the documentation**
+
+```bash
+doxygen Doc/doxygen.cfg
+```
+
+Alternatively, you can enable the `DILIGENT_BUILD_DOCS` CMake option to add the `DiligentDocs` target.
+
+The generated documentation will be placed in `build/docs/html`.
+Open `build/docs/html/index.html` in your browser to view the documentation.

README.md

@@ -724,6 +724,7 @@ Available CMake options are summarized in the table below:
 | `DILIGENT_BUILD_SAMPLE_BASE_ONLY`       |     No       | Build only SampleBase project and no other samples/tutorials |
 | `DILIGENT_BUILD_TESTS`                  |     No       | Build Unit Tests                                             |
 | `DILIGENT_BUILD_WIN32_GUI_AS_CONSOLE`   |     No       | Build Windows GUI applications using the console subsystem   |
+| `DILIGENT_BUILD_DOCS`                   |     No       | Build documentation using Doxygen                            |
 | `DILIGENT_NO_GLSLANG`                   |     No       | Do not build GLSLang and SPRIV-Tools                         |
 | `DILIGENT_NO_HLSL`                      |     No       | Disable HLSL support in non-Direct3D backends                |
 | `DILIGENT_NO_FORMAT_VALIDATION`         |     Yes      | Disable source code formatting validation                    |