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,28 @@
+# Building documentation
+
+To build the documentation, install Doxygen. 
+Check the required version in the [action file](https://github.com/DiligentGraphics/github-action/blob/master/install-doxygen/action.yml).
+
+Then run the following commands in the **root of the repository**.
+
+**1. Build markdown pages list**
+
+By default, Doxygen puts all markdown files in rather arbitrary order in a flat list.
+This looks very messy and is not user-friendly.
+The following script organizes the markdown files into a tree structure and generates a
+list of pages in the `Doc/pages.dox` file:
+
+```bash
+python Doc/md_pages.py Doc/pages.dox
+```
+
+**2. Build documentation**
+
+```bash
+doxygen Doc/doxygen.cfg
+```
+
+Use the `DILIGENT_BUILD_DOCS` CMake option to add `DiligentDocs` CMake targets for building documentation.
+
+The documentation will be generated in the `build/docs/html` folder.
+Open `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                    |