From 6fae0b83d9f0ddc28d6f1cadf3c8aef126004429 Mon Sep 17 00:00:00 2001 From: glx22 Date: Thu, 10 Dec 2020 23:57:27 +0100 Subject: [PATCH] Add: [CMake] targets to generate documentation --- CMakeLists.txt | 21 +++++++++++++++++++++ Doxyfile => Doxyfile.in | 8 +++----- cmake/scripts/FindVersion.cmake | 12 ++++++++++++ src/script/api/CMakeLists.txt | 17 +++++++++++++++++ src/script/api/{Doxyfile_AI => Doxyfile_AI.in} | 14 ++++---------- src/script/api/{Doxyfile_Game => Doxyfile_GS.in} | 14 ++++---------- 6 files changed, 61 insertions(+), 25 deletions(-) rename Doxyfile => Doxyfile.in (98%) rename src/script/api/{Doxyfile_AI => Doxyfile_AI.in} (96%) rename src/script/api/{Doxyfile_Game => Doxyfile_GS.in} (96%) diff --git a/CMakeLists.txt b/CMakeLists.txt index 39cfffc019..a8f7aa071a 100644 --- a/CMakeLists.txt +++ b/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() diff --git a/Doxyfile b/Doxyfile.in similarity index 98% rename from Doxyfile rename to Doxyfile.in index e288ffbd87..8727594771 100644 --- a/Doxyfile +++ b/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 diff --git a/cmake/scripts/FindVersion.cmake b/cmake/scripts/FindVersion.cmake index bb754fc5b3..c920e6b8c7 100644 --- a/cmake/scripts/FindVersion.cmake +++ b/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() diff --git a/src/script/api/CMakeLists.txt b/src/script/api/CMakeLists.txt index e294cfd05c..9bc4183f19 100644 --- a/src/script/api/CMakeLists.txt +++ b/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} diff --git a/src/script/api/Doxyfile_AI b/src/script/api/Doxyfile_AI.in similarity index 96% rename from src/script/api/Doxyfile_AI rename to src/script/api/Doxyfile_AI.in index fb0abc0567..f0707e0d86 100644 --- a/src/script/api/Doxyfile_AI +++ b/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 diff --git a/src/script/api/Doxyfile_Game b/src/script/api/Doxyfile_GS.in similarity index 96% rename from src/script/api/Doxyfile_Game rename to src/script/api/Doxyfile_GS.in index 83f8ad0e87..7dae7aad66 100644 --- a/src/script/api/Doxyfile_Game +++ b/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 -- 2.11.4.GIT