Skip to content

Commit 630e17b

Browse files
imbobzimbobz
committed
Build: improve documentatyion generation usage
export 2 functions; one that generate pdf, second generate html. Use cmake option to tell cmake wich one to generate
1 parent e37fd95 commit 630e17b

5 files changed

Lines changed: 63 additions & 46 deletions

File tree

‎CMakeLists.txt‎

Lines changed: 9 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -9,6 +9,8 @@ project(cae
99

1010
list(APPEND CMAKE_MODULE_PATH "${PROJECT_SOURCE_DIR}/cmake/modules")
1111

12+
option(CAE_BUILD_DOC_HTML "Build html documentation" OFF)
13+
option(CAE_BUILD_DOC_PDF "Build pdf documentation" OFF)
1214
option(CAE_CLANG_FORMAT "Enable clang-format" OFF)
1315

1416
file(GLOB_RECURSE PROJECT_FILES
@@ -30,7 +32,13 @@ include(CompileOptions)
3032

3133
if (CAE_CLANG_FORMAT)
3234
format_project(${PROJECT_FILES})
33-
endif()
35+
endif ()
36+
37+
if (CAE_BUILD_DOC_HTML)
38+
cae_add_doxygen_html(cae-doc-html ${PROJECT_FILES})
39+
elseif (CAE_BUILD_DOC_PDF)
40+
cae_add_doxygen_pdf(cae-doc-pdf ${PROJECT_FILES})
41+
endif ()
3442

3543
find_package(nlohmann_json QUIET CONFIG)
3644
if (NOT nlohmann_json_FOUND)

‎README.md‎

Lines changed: 6 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -75,13 +75,14 @@ This section targets engine developers and contributors.
7575

7676
### CMake Build options
7777

78-
- `CAE_STRICT_WARNINGS` (default: `OFF`): Enable strict warning level.
79-
- `CAE_ENABLE_SANITIZERS` (default: `OFF`): Enable address and undefined sanitizers.
80-
- `CAE_ENABLE_LTO` (default: `OFF`): Enable LTO on final targets.
78+
- `CAE_BUILD_DOC_HTML` (default: `OFF`): Enable building doxygen html documentation.
79+
- `CAE_BUILD_DOC_PDF` (default: `OFF`): Enable building doxygen pdf documentation.
8180
- `CAE_BUILD_TESTS` (default: `OFF`): Enable building unit tests.
82-
- `CAE_CLANG_TIDY` (default: `OFF`): Enable clang tidy usage.
8381
- `CAE_CLANG_FORMAT` (default: `OFF`): Enable clang format usage.
84-
- `CAE_BUILD_DOC` (default: `OFF`): Enable building doxygen documentation.
82+
- `CAE_CLANG_TIDY` (default: `OFF`): Enable clang tidy usage.
83+
- `CAE_ENABLE_LTO` (default: `OFF`): Enable LTO on final targets.
84+
- `CAE_ENABLE_SANITIZERS` (default: `OFF`): Enable address and undefined sanitizers.
85+
- `CAE_STRICT_WARNINGS` (default: `OFF`): Enable strict warning level.
8586

8687
### Preprocessor macros
8788

‎cmake/modules/MakeDoc.cmake‎

Lines changed: 32 additions & 24 deletions
Original file line numberDiff line numberDiff line change
@@ -1,29 +1,37 @@
1-
option(CAE_BUILD_DOC "Build documentation" OFF)
2-
3-
if (NOT CAE_BUILD_DOC)
4-
return()
5-
endif()
1+
include_guard(GLOBAL)
62

73
find_package(Doxygen REQUIRED)
84

9-
file(DOWNLOAD https://raw.githubusercontent.com/jothepro/doxygen-awesome-css/v2.4.1/doxygen-awesome.css
10-
${CMAKE_CURRENT_BINARY_DIR}/doxygen-awesome.css)
11-
file(DOWNLOAD https://raw.githubusercontent.com/jothepro/doxygen-awesome-css/v2.4.1/doxygen-awesome-sidebar-only.css
12-
${CMAKE_CURRENT_BINARY_DIR}/doxygen-awesome-sidebar-only.css)
13-
145
set(DOXYGEN_DIR "${CMAKE_SOURCE_DIR}/documentation/.doxygen")
156
set(DOXYFILE_OUT "${CMAKE_CURRENT_BINARY_DIR}/Doxyfile")
16-
configure_file("${DOXYGEN_DIR}/Doxyfile" ${DOXYFILE_OUT} @ONLY)
17-
doxygen_add_docs(doxygen ${PROJECT_FILES})
18-
add_custom_command(TARGET doxygen POST_BUILD
19-
WORKING_DIRECTORY ${DOXYGEN_DIR}
20-
COMMAND ${DOXYGEN_EXECUTABLE} ${DOXYFILE_OUT}
21-
VERBATIM
22-
)
23-
add_custom_command(TARGET doxygen POST_BUILD
24-
WORKING_DIRECTORY "${DOXYGEN_DIR}/latex"
25-
COMMAND make > /dev/null
26-
COMMAND ${CMAKE_COMMAND} -E copy "refman.pdf" "${CMAKE_SOURCE_DIR}/documentation/${PROJECT_NAME}.pdf"
27-
BYPRODUCTS "${CMAKE_SOURCE_DIR}/documentation/${PROJECT_NAME}.pdf"
28-
VERBATIM
29-
)
7+
8+
function(cae_download_extra_css)
9+
file(DOWNLOAD "https://raw.githubusercontent.com/jothepro/doxygen-awesome-css/v2.4.1/doxygen-awesome.css"
10+
"${DOXYGEN_DIR}/css/doxygen-awesome.css")
11+
file(DOWNLOAD "https://raw.githubusercontent.com/jothepro/doxygen-awesome-css/v2.4.1/doxygen-awesome-sidebar-only.css"
12+
"${DOXYGEN_DIR}/css/doxygen-awesome-sidebar-only.css")
13+
endfunction()
14+
15+
function(cae_add_doxygen_html TARGET FILES)
16+
configure_file("${DOXYGEN_DIR}/Doxyfile" ${DOXYFILE_OUT} @ONLY)
17+
cae_download_extra_css()
18+
doxygen_add_docs(${TARGET} ${FILES})
19+
add_custom_command(TARGET ${TARGET} POST_BUILD
20+
WORKING_DIRECTORY ${DOXYGEN_DIR}
21+
COMMAND ${DOXYGEN_EXECUTABLE} ${DOXYFILE_OUT}
22+
VERBATIM
23+
)
24+
endfunction()
25+
26+
function(cae_add_doxygen_pdf TARGET FILES)
27+
configure_file("${DOXYGEN_DIR}/Doxyfile" ${DOXYFILE_OUT} @ONLY)
28+
cae_download_extra_css()
29+
doxygen_add_docs(${TARGET} ${FILES})
30+
add_custom_command(TARGET ${TARGET} POST_BUILD
31+
WORKING_DIRECTORY "${DOXYGEN_DIR}/latex"
32+
COMMAND make > /dev/null
33+
COMMAND ${CMAKE_COMMAND} -E copy "refman.pdf" "${CMAKE_SOURCE_DIR}/documentation/${PROJECT_NAME}.pdf"
34+
BYPRODUCTS "${CMAKE_SOURCE_DIR}/documentation/${PROJECT_NAME}.pdf"
35+
VERBATIM
36+
)
37+
endfunction()

‎documentation/.doxygen/Doxyfile‎

Lines changed: 15 additions & 16 deletions
Original file line numberDiff line numberDiff line change
@@ -1,35 +1,34 @@
1-
HTML_EXTRA_FILES = @CMAKE_CURRENT_SOURCE_DIR@/assets/icons/favicon.ico
2-
HTML_EXTRA_STYLESHEET = @CMAKE_CURRENT_BINARY_DIR@/doxygen-awesome.css \
3-
@CMAKE_CURRENT_BINARY_DIR@/doxygen-awesome-sidebar-only.css
4-
HTML_HEADER = @CMAKE_CURRENT_SOURCE_DIR@/documentation/.doxygen/header.html
1+
HTML_EXTRA_FILES = @CMAKE_SOURCE_DIR@/assets/icons/favicon.ico
2+
HTML_EXTRA_STYLESHEET = @CMAKE_SOURCE_DIR@/documentation/.doxygen/css/doxygen-awesome.css \
3+
@CMAKE_SOURCE_DIR@/documentation/.doxygen/css/doxygen-awesome-sidebar-only.css
4+
HTML_HEADER = @CMAKE_SOURCE_DIR@/documentation/.doxygen/header.html
55

6-
IMAGE_PATH = @CMAKE_CURRENT_SOURCE_DIR@/assets/icons/
6+
IMAGE_PATH = @CMAKE_SOURCE_DIR@/assets/icons/
77

88
QUIET = NO
99
GENERATE_HTML = YES
1010
GENERATE_LATEX = YES
1111
LATEX_CMD_NAME = xelatex
1212

13-
PROJECT_LOGO = @CMAKE_CURRENT_SOURCE_DIR@/assets/icons/icon.svg
13+
PROJECT_LOGO = @CMAKE_SOURCE_DIR@/assets/icons/icon.svg
1414
PROJECT_NAME = "@CMAKE_PROJECT_NAME@"
1515
PROJECT_NUMBER = @PROJECT_VERSION_MAJOR@.@PROJECT_VERSION_MINOR@.@PROJECT_VERSION_PATCH@
1616
PROJECT_BRIEF = "@CMAKE_PROJECT_DESCRIPTION@"
1717

18-
STRIP_FROM_PATH = @CMAKE_CURRENT_SOURCE_DIR@ \
19-
@PROJECT_SOURCE_DIR@
20-
INPUT = @CMAKE_CURRENT_SOURCE_DIR@/include \
21-
@CMAKE_CURRENT_SOURCE_DIR@/src \
22-
@CMAKE_CURRENT_SOURCE_DIR@/plugins \
23-
@CMAKE_CURRENT_SOURCE_DIR@/modules \
24-
@CMAKE_CURRENT_SOURCE_DIR@/CONTRIBUTING.md \
25-
@CMAKE_CURRENT_SOURCE_DIR@/LICENSE.md \
26-
@CMAKE_CURRENT_SOURCE_DIR@/README.md
18+
STRIP_FROM_PATH = @CMAKE_SOURCE_DIR@
19+
INPUT = @CMAKE_SOURCE_DIR@/include \
20+
@CMAKE_SOURCE_DIR@/src \
21+
@CMAKE_SOURCE_DIR@/plugins \
22+
@CMAKE_SOURCE_DIR@/modules \
23+
@CMAKE_SOURCE_DIR@/CONTRIBUTING.md \
24+
@CMAKE_SOURCE_DIR@/LICENSE.md \
25+
@CMAKE_SOURCE_DIR@/README.md
2726
FILE_PATTERNS = *.hpp \
2827
*.cpp \
2928
*.md
3029
EXCLUDE_PATTERNS = third-party/*
3130
RECURSIVE = YES
32-
USE_MDFILE_AS_MAINPAGE = "@CMAKE_CURRENT_SOURCE_DIR@/README.md"
31+
USE_MDFILE_AS_MAINPAGE = "@CMAKE_SOURCE_DIR@/README.md"
3332

3433
PLANTUML_JAR_PATH =
3534
DOT_PATH =

‎documentation/.gitignore‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,2 +1,3 @@
1+
.doxygen/css
12
.doxygen/html
23
.doxygen/latex

0 commit comments

Comments
 (0)