Add: [CMake] targets to generate documentation

CMakeLists.txt

@@ -72,6 +72,10 @@ find_package(Xaudio2)
 
 find_package(Grfcodec)
 
+if(UNIX)
+    find_package(Doxygen)
+endif()
+
 # IPO is only properly supported from CMake 3.9. Despite the fact we are
 # CMake 3.5, still enable IPO if we detect we are 3.9+.
 if(POLICY CMP0069)
@@ -130,6 +134,23 @@ add_custom_target(find_version
 # An empty target for the tools
 add_custom_target(tools)
 
+# Documentation
+if(DOXYGEN_EXECUTABLE)
+    add_custom_target(docs)
+    add_custom_target(docs_source
+        ${CMAKE_COMMAND} -E make_directory ${CMAKE_BINARY_DIR}/docs
+        COMMAND ${DOXYGEN_EXECUTABLE} ${CMAKE_BINARY_DIR}/Doxyfile
+        WORKING_DIRECTORY ${CMAKE_SOURCE_DIR}
+        COMMENT "Generating documentation for source"
+    )
+    add_dependencies(docs_source
+        find_version
+    )
+    add_dependencies(docs
+        docs_source
+    )
+endif()
+
 include(SourceList)
 include(Endian)
 add_endian_definition()

Doxyfile.in

@@ -8,10 +8,10 @@
 #---------------------------------------------------------------------------
 DOXYFILE_ENCODING      = UTF-8
 PROJECT_NAME           = "OpenTTD Source"
-PROJECT_NUMBER         = $(VERSION)
+PROJECT_NUMBER         = ${REV_VERSION}
 PROJECT_BRIEF          =
 PROJECT_LOGO           =
-OUTPUT_DIRECTORY       = docs/source/
+OUTPUT_DIRECTORY       = ${CPACK_BINARY_DIR}/docs/source/
 CREATE_SUBDIRS         = YES
 ALLOW_UNICODE_NAMES    = NO
 OUTPUT_LANGUAGE        = English
@@ -306,16 +306,14 @@ SKIP_FUNCTION_MACROS   = YES
 # Configuration options related to external references
 #---------------------------------------------------------------------------
 TAGFILES               =
-GENERATE_TAGFILE       = objs/openttd.tag
+GENERATE_TAGFILE       = ${CPACK_BINARY_DIR}/docs/openttd.tag
 ALLEXTERNALS           = NO
 EXTERNAL_GROUPS        = YES
 EXTERNAL_PAGES         = YES
-PERL_PATH              = /usr/bin/perl
 #---------------------------------------------------------------------------
 # Configuration options related to the dot tool
 #---------------------------------------------------------------------------
 CLASS_DIAGRAMS         = YES
-MSCGEN_PATH            =
 DIA_PATH               =
 HIDE_UNDOC_RELATIONS   = YES
 HAVE_DOT               = NO

cmake/scripts/FindVersion.cmake

@@ -137,4 +137,16 @@ else()
     message(STATUS "Generating CPackProperties.cmake")
     configure_file("${CMAKE_SOURCE_DIR}/CPackProperties.cmake.in"
             "${CPACK_BINARY_DIR}/CPackProperties.cmake" @ONLY)
+
+    message(STATUS "Generating Doxyfile")
+    configure_file("${CMAKE_SOURCE_DIR}/Doxyfile.in"
+            "${CPACK_BINARY_DIR}/Doxyfile")
+
+    message(STATUS "Generating Doxyfile_AI")
+    configure_file("${CMAKE_SOURCE_DIR}/src/script/api/Doxyfile_AI.in"
+            "${CPACK_BINARY_DIR}/Doxyfile_AI")
+
+    message(STATUS "Generating Doxyfile_GS")
+    configure_file("${CMAKE_SOURCE_DIR}/src/script/api/Doxyfile_GS.in"
+            "${CPACK_BINARY_DIR}/Doxyfile_GS")
 endif()

src/script/api/CMakeLists.txt

@@ -100,6 +100,23 @@ foreach(API "ai;AI" "game;GS" "template;Template")
         add_dependencies(script_api
                 script_${APILC}_includes
         )
+
+        # Documentation
+        if(DOXYGEN_EXECUTABLE)
+            add_custom_target(docs_${APILC}
+                ${CMAKE_COMMAND} -E make_directory ${CMAKE_BINARY_DIR}/docs
+                COMMAND ${DOXYGEN_EXECUTABLE} ${CMAKE_BINARY_DIR}/Doxyfile_${APIUC}
+                WORKING_DIRECTORY ${CMAKE_CURRENT_SOURCE_DIR}
+                COMMENT "Generating documentation for ${APILC} API"
+            )
+            add_dependencies(docs_${APILC}
+                find_version
+                script_window
+            )
+            add_dependencies(docs
+                docs_${APILC}
+            )
+        endif()
     else()
         add_dependencies(script_api
                 script_${APILC}

src/script/api/Doxyfile_AI.in

@@ -10,8 +10,8 @@
 #---------------------------------------------------------------------------
 DOXYFILE_ENCODING      = UTF-8
 PROJECT_NAME           = "OpenTTD AI API"
-PROJECT_NUMBER         = $(VERSION)
-OUTPUT_DIRECTORY       = ../../../docs/aidocs/
+PROJECT_NUMBER         = ${REV_VERSION}
+OUTPUT_DIRECTORY       = ${CPACK_BINARY_DIR}/docs/ai-api/
 CREATE_SUBDIRS         = NO
 OUTPUT_LANGUAGE        = English
 BRIEF_MEMBER_DESC      = YES
@@ -76,7 +76,6 @@ GENERATE_DEPRECATEDLIST= NO
 ENABLED_SECTIONS       =
 MAX_INITIALIZER_LINES  = 30
 SHOW_USED_FILES        = NO
-SHOW_DIRECTORIES       = NO
 FILE_VERSION_FILTER    =
 #---------------------------------------------------------------------------
 # configuration options related to warning and progress messages
@@ -91,7 +90,7 @@ WARN_LOGFILE           =
 #---------------------------------------------------------------------------
 # configuration options related to the input files
 #---------------------------------------------------------------------------
-INPUT                  = . $(GENERATED_API_DIR)
+INPUT                  = . ${FIND_VERSION_BINARY_DIR}/script/api
 INPUT_ENCODING         = UTF-8
 FILE_PATTERNS          = script_*.hpp \
                          ai_*.hpp
@@ -133,7 +132,6 @@ HTML_FILE_EXTENSION    = .html
 HTML_HEADER            =
 HTML_FOOTER            =
 HTML_STYLESHEET        =
-HTML_ALIGN_MEMBERS     = YES
 GENERATE_HTMLHELP      = NO
 HTML_DYNAMIC_SECTIONS  = NO
 CHM_FILE               =
@@ -181,8 +179,6 @@ MAN_LINKS              = NO
 #---------------------------------------------------------------------------
 GENERATE_XML           = NO
 XML_OUTPUT             = xml
-XML_SCHEMA             =
-XML_DTD                =
 XML_PROGRAMLISTING     = YES
 #---------------------------------------------------------------------------
 # configuration options for the AutoGen Definitions output
@@ -211,15 +207,13 @@ SKIP_FUNCTION_MACROS   = YES
 # Configuration::additions related to external references
 #---------------------------------------------------------------------------
 TAGFILES               =
-GENERATE_TAGFILE       = ../../../objs/openttd_noai.tag
+GENERATE_TAGFILE       = ${CPACK_BINARY_DIR}/docs/openttd_ai_api.tag
 ALLEXTERNALS           = NO
 EXTERNAL_GROUPS        = YES
-PERL_PATH              = /usr/bin/perl
 #---------------------------------------------------------------------------
 # Configuration options related to the dot tool
 #---------------------------------------------------------------------------
 CLASS_DIAGRAMS         = YES
-MSCGEN_PATH            =
 HIDE_UNDOC_RELATIONS   = YES
 HAVE_DOT               = NO
 CLASS_GRAPH            = YES

src/script/api/Doxyfile_GS.in

@@ -10,8 +10,8 @@
 #---------------------------------------------------------------------------
 DOXYFILE_ENCODING      = UTF-8
 PROJECT_NAME           = "OpenTTD GameScript API"
-PROJECT_NUMBER         = $(VERSION)
-OUTPUT_DIRECTORY       = ../../../docs/gamedocs/
+PROJECT_NUMBER         = ${REV_VERSION}
+OUTPUT_DIRECTORY       = ${CPACK_BINARY_DIR}/docs/gs-api/
 CREATE_SUBDIRS         = NO
 OUTPUT_LANGUAGE        = English
 BRIEF_MEMBER_DESC      = YES
@@ -76,7 +76,6 @@ GENERATE_DEPRECATEDLIST= NO
 ENABLED_SECTIONS       =
 MAX_INITIALIZER_LINES  = 30
 SHOW_USED_FILES        = NO
-SHOW_DIRECTORIES       = NO
 FILE_VERSION_FILTER    =
 #---------------------------------------------------------------------------
 # configuration options related to warning and progress messages
@@ -91,7 +90,7 @@ WARN_LOGFILE           =
 #---------------------------------------------------------------------------
 # configuration options related to the input files
 #---------------------------------------------------------------------------
-INPUT                  = . $(GENERATED_API_DIR)
+INPUT                  = . ${FIND_VERSION_BINARY_DIR}/script/api
 INPUT_ENCODING         = UTF-8
 FILE_PATTERNS          = script_*.hpp \
                          game_*.hpp
@@ -133,7 +132,6 @@ HTML_FILE_EXTENSION    = .html
 HTML_HEADER            =
 HTML_FOOTER            =
 HTML_STYLESHEET        =
-HTML_ALIGN_MEMBERS     = YES
 GENERATE_HTMLHELP      = NO
 HTML_DYNAMIC_SECTIONS  = NO
 CHM_FILE               =
@@ -181,8 +179,6 @@ MAN_LINKS              = NO
 #---------------------------------------------------------------------------
 GENERATE_XML           = NO
 XML_OUTPUT             = xml
-XML_SCHEMA             =
-XML_DTD                =
 XML_PROGRAMLISTING     = YES
 #---------------------------------------------------------------------------
 # configuration options for the AutoGen Definitions output
@@ -211,15 +207,13 @@ SKIP_FUNCTION_MACROS   = YES
 # Configuration::additions related to external references
 #---------------------------------------------------------------------------
 TAGFILES               =
-GENERATE_TAGFILE       = ../../../objs/openttd_nogo.tag
+GENERATE_TAGFILE       = ${CPACK_BINARY_DIR}/docs/openttd_gs_api.tag
 ALLEXTERNALS           = NO
 EXTERNAL_GROUPS        = YES
-PERL_PATH              = /usr/bin/perl
 #---------------------------------------------------------------------------
 # Configuration options related to the dot tool
 #---------------------------------------------------------------------------
 CLASS_DIAGRAMS         = YES
-MSCGEN_PATH            =
 HIDE_UNDOC_RELATIONS   = YES
 HAVE_DOT               = NO
 CLASS_GRAPH            = YES