Working on documentation

Author: DanielChappuis

CMakeLists.txt

@@ -31,6 +31,7 @@ enable_testing()
 option(RP3D_COMPILE_TESTBED "Select this if you want to build the testbed application with demos" OFF)
 option(RP3D_COMPILE_TESTS "Select this if you want to build the unit tests" OFF)
 option(RP3D_PROFILING_ENABLED "Select this if you want to compile for performanace profiling" OFF)
+option(RP3D_GENERATE_DOCUMENTATION "Select this if you want to generate the project documentation" OFF)
 option(RP3D_CODE_COVERAGE_ENABLED "Select this if you need to build for code coverage calculation" OFF)
 option(RP3D_DOUBLE_PRECISION_ENABLED "Select this if you want to compile using double precision floating values" OFF)
 
@@ -274,6 +275,11 @@ if(RP3D_COMPILE_TESTS)
    add_subdirectory(test/)
 endif()
 
+# Documentation generation
+if(RP3D_GENERATE_DOCUMENTATION)
+   add_subdirectory(documentation/)
+endif()
+
 # Enable profiling if necessary
 if(RP3D_PROFILING_ENABLED)
     target_compile_definitions(reactphysics3d PUBLIC IS_RP3D_PROFILING_ENABLED)

documentation/CMakeLists.txt

@@ -0,0 +1,48 @@
+
+# ---------- DOXYGEN ---------- #
+
+# Find the installed doxygen executable
+find_package(Doxygen REQUIRED)
+
+# Set variables
+set(DOXYGEN_OUTPUT_DIR ${CMAKE_CURRENT_BINARY_DIR}/doxygen)
+set(DOXYGEN_INDEX_FILE ${DOXYGEN_OUTPUT_DIR}/xml/index.xml)
+set(DOXYFILE_IN ${CMAKE_CURRENT_SOURCE_DIR}/doxygen/Doxyfile.in)
+set(DOXYFILE_OUT ${DOXYGEN_OUTPUT_DIR}/Doxyfile)
+
+# Replace variables inside @@ with the current values in the Doxyfile.in and export to Doxyfile
+configure_file(${DOXYFILE_IN} ${DOXYFILE_OUT} @ONLY)
+
+# Create the Doxygen output directory
+file(MAKE_DIRECTORY ${DOXYGEN_OUTPUT_DIR})
+add_custom_command(OUTPUT ${DOXYGEN_INDEX_FILE}
+                   COMMAND ${DOXYGEN_EXECUTABLE} ${DOXYFILE_OUT}
+                   MAIN_DEPENDENCY ${DOXYFILE_OUT} ${DOXYFILE_IN}
+		   COMMENT "Generating documentation with Doxygen")
+
+add_custom_target(Doxygen ALL DEPENDS ${DOXYGEN_INDEX_FILE})
+
+# ---------- SPHINX ---------- #
+
+find_package(Sphinx REQUIRED)
+
+set(SPHINX_SOURCE ${CMAKE_CURRENT_SOURCE_DIR}/sphinx/source)
+set(SPHINX_BUILD ${CMAKE_CURRENT_BINARY_DIR}/sphinx)
+set(SPHINX_INDEX_FILE ${SPHINX_BUILD}/index.html)
+
+add_custom_command(OUTPUT ${SPHINX_INDEX_FILE}
+                   COMMAND 
+                     ${SPHINX_EXECUTABLE} -b html
+                     # Tell Breathe where to find the Doxygen output
+		     -Dbreathe_projects.ReactPhysics3D=${DOXYGEN_OUTPUT_DIR}/xml
+                   ${SPHINX_SOURCE} ${SPHINX_BUILD}
+                   WORKING_DIRECTORY ${CMAKE_CURRENT_BINARY_DIR}
+                   DEPENDS
+                   # Other docs files you want to track should go here (or in some variable)
+		   ${SPHINX_SOURCE}/index.rst
+                   ${DOXYGEN_INDEX_FILE}
+                   MAIN_DEPENDENCY ${SPHINX_SOURCE}/conf.py
+                   COMMENT "Generating documentation with Sphinx")
+	   
+# Sphinx target
+add_custom_target(Sphinx ALL DEPENDS ${SPHINX_INDEX_FILE})

documentation/README.md

@@ -0,0 +1,15 @@
+
+ This file describes how the documentation of the project is generated.
+
+ Reference: https://devblogs.microsoft.com/cppblog/clear-functional-c-documentation-with-sphinx-breathe-doxygen-cmake
+
+ # Dependencies
+
+  - Doxygen
+  - Sphinx
+  - Breathe (bridge between Doxygen and Sphinx)
+  - CMake
+
+ # How to generate the documentation
+
+

documentation/API/Doxyfile documentation/doxygen/Doxyfile.indocumentation/API/Doxyfile renamed to documentation/doxygen/Doxyfile.in

@@ -58,7 +58,7 @@ PROJECT_LOGO           = "ReactPhysics3DLogo.png"
 # entered, it will be relative to the location where doxygen was started. If
 # left blank the current directory will be used.
 
-OUTPUT_DIRECTORY       =
+OUTPUT_DIRECTORY       = "@DOXYGEN_OUTPUT_DIR@"
 
 # If the CREATE_SUBDIRS tag is set to YES then doxygen will create 4096 sub-
 # directories (in 2 levels) under the output directory of each output format and
@@ -230,12 +230,6 @@ TAB_SIZE               = 4
 
 ALIASES                =
 
-# This tag can be used to specify a number of word-keyword mappings (TCL only).
-# A mapping has the form "name=value". For example adding "class=itcl::class"
-# will allow you to use the command class in the itcl::class meaning.
-
-TCL_SUBST              =
-
 # Set the OPTIMIZE_OUTPUT_FOR_C tag to YES if your project consists of C sources
 # only. Doxygen will then generate output that is more tailored for C. For
 # instance, some of the names that are used will be different. The list of all
@@ -780,7 +774,7 @@ WARN_LOGFILE           =
 # spaces. See also FILE_PATTERNS and EXTENSION_MAPPING
 # Note: If this tag is empty the current directory is searched.
 
-INPUT                  = "../../src/" "../../include/reactphysics3d/"
+INPUT                  = @PROJECT_SOURCE_DIR@/"src/" @PROJECT_SOURCE_DIR@/"include/reactphysics3d/"
 
 # This tag can be used to specify the character encoding of the source files
 # that doxygen parses. Internally doxygen uses the UTF-8 encoding. Doxygen uses
@@ -1048,13 +1042,6 @@ CLANG_OPTIONS          =
 
 ALPHABETICAL_INDEX     = YES
 
-# The COLS_IN_ALPHA_INDEX tag can be used to specify the number of columns in
-# which the alphabetical index list will be split.
-# Minimum value: 1, maximum value: 20, default value: 5.
-# This tag requires that the tag ALPHABETICAL_INDEX is set to YES.
-
-COLS_IN_ALPHA_INDEX    = 5
-
 # In case all classes in a project start with a common prefix, all classes will
 # be put under the same header in the alphabetical index. The IGNORE_PREFIX tag
 # can be used to specify a prefix (or a list of prefixes) that should be ignored
@@ -1070,7 +1057,7 @@ IGNORE_PREFIX          =
 # If the GENERATE_HTML tag is set to YES, doxygen will generate HTML output
 # The default value is: YES.
 
-GENERATE_HTML          = YES
+GENERATE_HTML          = NO
 
 # The HTML_OUTPUT tag is used to specify where the HTML docs will be put. If a
 # relative path is entered the value of OUTPUT_DIRECTORY will be put in front of
@@ -1894,7 +1881,7 @@ MAN_LINKS              = NO
 # captures the structure of the code including all documentation.
 # The default value is: NO.
 
-GENERATE_XML           = NO
+GENERATE_XML           = YES
 
 # The XML_OUTPUT tag is used to specify where the XML pages will be put. If a
 # relative path is entered the value of OUTPUT_DIRECTORY will be put in front of
@@ -2114,12 +2101,6 @@ EXTERNAL_GROUPS        = YES
 
 EXTERNAL_PAGES         = YES
 
-# The PERL_PATH should be the absolute path and name of the perl script
-# interpreter (i.e. the result of 'which perl').
-# The default file (with absolute path) is: /usr/bin/perl.
-
-PERL_PATH              = /usr/bin/perl
-
 #---------------------------------------------------------------------------
 # Configuration options related to the dot tool
 #---------------------------------------------------------------------------
@@ -2133,15 +2114,6 @@ PERL_PATH              = /usr/bin/perl
 
 CLASS_DIAGRAMS         = YES
 
-# You can define message sequence charts within doxygen comments using the \msc
-# command. Doxygen will then run the mscgen tool (see:
-# http://www.mcternan.me.uk/mscgen/)) to produce the chart and insert it in the
-# documentation. The MSCGEN_PATH tag allows you to specify the directory where
-# the mscgen tool resides. If left empty the tool is assumed to be found in the
-# default search path.
-
-MSCGEN_PATH            =
-
 # You can include diagrams made with dia in doxygen documentation. Doxygen will
 # then run dia to produce the diagram and insert it in the documentation. The
 # DIA_PATH tag allows you to specify the directory where the dia binary resides.

documentation/sphinx/source/conf.py

@@ -0,0 +1,33 @@
+# Configuration file for the Sphinx documentation builder.
+#
+# For the full list of built-in configuration values, see the documentation:
+# https://www.sphinx-doc.org/en/master/usage/configuration.html
+
+# -- Project information -----------------------------------------------------
+# https://www.sphinx-doc.org/en/master/usage/configuration.html#project-information
+
+project = 'ReactPhysics3D'
+copyright = '2024, Daniel Chappuis'
+author = 'Daniel Chappuis'
+release = 'v0.10.0'
+
+# -- General configuration ---------------------------------------------------
+# https://www.sphinx-doc.org/en/master/usage/configuration.html#general-configuration
+
+extensions = ["breathe"]
+
+templates_path = ['_templates']
+exclude_patterns = []
+
+
+
+# -- Options for HTML output -------------------------------------------------
+# https://www.sphinx-doc.org/en/master/usage/configuration.html#options-for-html-output
+
+html_theme = 'sphinx_rtd_theme'
+html_static_path = ['_static']
+
+# Breathe Configuration
+breathe_default_project = "ReactPhysics3D"
+
+highlight_language = 'c++'