Skip to content

Commit 671b494

Browse files
ReenigneArcherReenigneArcher
committed
feat: initial version
1 parent 20372c1 commit 671b494

File tree

11 files changed

+583
-2
lines changed

11 files changed

+583
-2
lines changed

‎.gitignore

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,6 @@
1+
# Ignore JetBrains IDE files
2+
.idea/
3+
4+
# npm
5+
node_modules/
6+
package-lock.json

‎.gitmodules

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,4 @@
1+
[submodule "doxygen-awesome-css"]
2+
path = doxygen-awesome-css
3+
url = https://github.com/jothepro/doxygen-awesome-css.git
4+
branch = main

‎.readthedocs.yaml

Lines changed: 40 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,40 @@
1+
---
2+
# .readthedocs.yaml
3+
# Read the Docs configuration file
4+
# See https://docs.readthedocs.io/en/stable/config-file/v2.html for details
5+
6+
version: 2
7+
8+
build:
9+
os: ubuntu-24.04
10+
tools:
11+
python: "miniconda-latest"
12+
commands:
13+
# because we are overriding the build commands, we need to setup the environment ourselves
14+
- cat third-party/doxyconfig/environment.yml
15+
- conda env create --quiet --name ${READTHEDOCS_VERSION} --file third-party/doxyconfig/environment.yml
16+
- npm install "@fortawesome/fontawesome-free"
17+
- mkdir -p ${READTHEDOCS_OUTPUT}html/assets/fontawesome/css
18+
- mkdir -p ${READTHEDOCS_OUTPUT}html/assets/fontawesome/js
19+
- cp node_modules/@fortawesome/fontawesome-free/css/all.min.css ${READTHEDOCS_OUTPUT}html/assets/fontawesome/css
20+
- cp node_modules/@fortawesome/fontawesome-free/js/all.min.js ${READTHEDOCS_OUTPUT}html/assets/fontawesome/js
21+
- cp -r node_modules/@fortawesome/fontawesome-free/webfonts ${READTHEDOCS_OUTPUT}html/assets/fontawesome/
22+
- |
23+
wget "https://raw.githubusercontent.com/LizardByte/.github/master/branding/logos/favicon.ico" \
24+
-O ${READTHEDOCS_OUTPUT}lizardbyte.ico
25+
- |
26+
wget "https://raw.githubusercontent.com/LizardByte/.github/master/branding/logos/logo-128x128.png" \
27+
-O ${READTHEDOCS_OUTPUT}lizardbyte.png
28+
- cp ./third-party/doxyconfig/Doxyfile ./docs/Doxyfile-doxyconfig
29+
- cp ./third-party/doxyconfig/header.html ./docs/header-doxyconfig.html
30+
- cat ./docs/Doxyfile >> ./docs/Doxyfile-doxyconfig
31+
- cd docs && doxygen Doxyfile-doxyconfig
32+
33+
# using conda, we can get newer doxygen and graphviz than ubuntu provide
34+
# https://github.com/readthedocs/readthedocs.org/issues/8151#issuecomment-890359661
35+
conda:
36+
environment: third-party/doxyconfig/environment.yml
37+
38+
submodules:
39+
include: all
40+
recursive: true

‎CMakeLists.txt

Lines changed: 92 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,92 @@
1+
# find doxygen and graphviz
2+
find_package(Doxygen 1.10 REQUIRED dot) # debian and ubuntu left in the dust
3+
4+
# get parent project docs directory
5+
set(SOURCE_DOCS_DIR "${CMAKE_SOURCE_DIR}/docs")
6+
7+
# fail if the directory does not exist
8+
if(NOT EXISTS ${SOURCE_DOCS_DIR})
9+
message(FATAL_ERROR "Directory ${SOURCE_DOCS_DIR} does not exist")
10+
endif()
11+
12+
# define variables based on whether we are building on readthedocs
13+
if(DEFINED ENV{READTHEDOCS})
14+
set(DOXYGEN_BUILD_DIR_CMAKE $ENV{READTHEDOCS_OUTPUT})
15+
set(DOXYGEN_PROJECT_VERSION $ENV{READTHEDOCS_VERSION})
16+
else()
17+
set(DOXYGEN_BUILD_DIR_CMAKE "${CMAKE_CURRENT_BINARY_DIR}/build")
18+
set(DOXYGEN_PROJECT_VERSION ${PROJECT_VERSION})
19+
endif()
20+
message(STATUS "DOXYGEN_BUILD_DIR_CMAKE: ${DOXYGEN_BUILD_DIR_CMAKE}")
21+
22+
# create build directories, as doxygen fails to create it in some cases?
23+
file(MAKE_DIRECTORY "${DOXYGEN_BUILD_DIR_CMAKE}/html")
24+
25+
# copy files to build directory
26+
file(COPY_FILE "${CMAKE_CURRENT_SOURCE_DIR}/header.html" "${SOURCE_DOCS_DIR}/header-doxyconfig.html")
27+
file(COPY_FILE "${CMAKE_CURRENT_SOURCE_DIR}/Doxyfile" "${SOURCE_DOCS_DIR}/Doxyfile-doxyconfig")
28+
29+
# append the "${SOURCE_DOCS_DIR}/Doxyfile to the Doxyfile-doxyconfig
30+
file(READ "${SOURCE_DOCS_DIR}/Doxyfile" DOXYFILE_CONTENTS)
31+
file(APPEND "${SOURCE_DOCS_DIR}/Doxyfile-doxyconfig" "${DOXYFILE_CONTENTS}")
32+
33+
# sunshine has its own icon and logo
34+
if(NOT ${CMAKE_PROJECT_NAME} STREQUAL "Sunshine")
35+
# download icon and logo
36+
file(DOWNLOAD
37+
"https://raw.githubusercontent.com/LizardByte/.github/master/branding/logos/favicon.ico"
38+
"${DOXYGEN_BUILD_DIR_CMAKE}/lizardbyte.ico"
39+
)
40+
file(DOWNLOAD
41+
"https://raw.githubusercontent.com/LizardByte/.github/master/branding/logos/logo-128x128.png"
42+
"${DOXYGEN_BUILD_DIR_CMAKE}/lizardbyte.png"
43+
)
44+
endif()
45+
46+
# set FONT_AWESOME_FILES depends
47+
set(FONT_AWESOME_FILES_DEPENDS
48+
"${CMAKE_CURRENT_SOURCE_DIR}/node_modules/@fortawesome/fontawesome-free/css/all.min.css"
49+
"${CMAKE_CURRENT_SOURCE_DIR}/node_modules/@fortawesome/fontawesome-free/js/all.min.js"
50+
"${CMAKE_CURRENT_SOURCE_DIR}/node_modules/@fortawesome/fontawesome-free/webfonts/"
51+
)
52+
53+
find_program(NPM npm REQUIRED)
54+
add_custom_target(_docs_fontawesome_install
55+
COMMENT "Installing node modules"
56+
BYPRODUCTS ${FONT_AWESOME_FILES_DEPENDS}
57+
COMMAND ${NPM} install
58+
WORKING_DIRECTORY "${CMAKE_CURRENT_SOURCE_DIR}"
59+
VERBATIM
60+
)
61+
62+
# copy Font Awesome files
63+
add_custom_command(
64+
OUTPUT FONT_AWESOME_FILES
65+
COMMAND ${CMAKE_COMMAND}
66+
-E copy ${CMAKE_CURRENT_SOURCE_DIR}/node_modules/@fortawesome/fontawesome-free/css/all.min.css
67+
${DOXYGEN_BUILD_DIR_CMAKE}/html/assets/fontawesome/css/all.min.css
68+
COMMAND ${CMAKE_COMMAND}
69+
-E copy ${CMAKE_CURRENT_SOURCE_DIR}/node_modules/@fortawesome/fontawesome-free/js/all.min.js
70+
${DOXYGEN_BUILD_DIR_CMAKE}/html/assets/fontawesome/js/all.min.js
71+
COMMAND ${CMAKE_COMMAND}
72+
-E copy_directory ${CMAKE_CURRENT_SOURCE_DIR}/node_modules/@fortawesome/fontawesome-free/webfonts
73+
${DOXYGEN_BUILD_DIR_CMAKE}/html/assets/fontawesome/webfonts
74+
COMMENT "Copying Font Awesome files"
75+
DEPENDS ${FONT_AWESOME_FILES_DEPENDS}
76+
)
77+
78+
# convert to relative path, so doxygen doesn't get confused on Windows
79+
file(RELATIVE_PATH DOXYGEN_BUILD_DIR_RELATIVE "${SOURCE_DOCS_DIR}" "${DOXYGEN_BUILD_DIR_CMAKE}")
80+
message(STATUS "DOXYGEN_BUILD_DIR_RELATIVE: ${DOXYGEN_BUILD_DIR_RELATIVE}")
81+
82+
# build docs
83+
add_custom_target(docs ALL
84+
COMMENT "Building Doxygen documentation"
85+
WORKING_DIRECTORY "${SOURCE_DOCS_DIR}"
86+
COMMAND ${CMAKE_COMMAND} -E env
87+
READTHEDOCS_OUTPUT=${DOXYGEN_BUILD_DIR_RELATIVE}
88+
READTHEDOCS_VERSION=${DOXYGEN_PROJECT_VERSION}
89+
${DOXYGEN_EXECUTABLE} Doxyfile-doxyconfig
90+
VERBATIM
91+
DEPENDS FONT_AWESOME_FILES
92+
)

‎Doxyfile

Lines changed: 131 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,131 @@
1+
# This file describes the settings to be used by the documentation system
2+
# doxygen (www.doxygen.org) for a project.
3+
#
4+
# All text after a double hash (##) is considered a comment and is placed in
5+
# front of the TAG it is preceding.
6+
#
7+
# All text after a single hash (#) is considered a comment and will be ignored.
8+
# The format is:
9+
# TAG = value [value, ...]
10+
# For lists, items can also be appended using:
11+
# TAG += value [value, ...]
12+
# Values that contain spaces should be placed between quotes (\" \").
13+
#
14+
# Note:
15+
#
16+
# Use doxygen to compare the used configuration file with the template
17+
# configuration file:
18+
# doxygen -x [configFile]
19+
# Use doxygen to compare the used configuration file with the template
20+
# configuration file without replacing the environment variables or CMake type
21+
# replacement variables:
22+
# doxygen -x_noenv [configFile]
23+
24+
# must be first
25+
DOXYFILE_ENCODING = UTF-8
26+
27+
#
28+
# Common LizardByte settings
29+
#
30+
31+
# LizardByte metadata
32+
DOCSET_PUBLISHER_NAME = LizardByte
33+
PROJECT_ICON = $(READTHEDOCS_OUTPUT)/lizardbyte.ico
34+
PROJECT_LOGO = $(READTHEDOCS_OUTPUT)/lizardbyte.png
35+
36+
# doxygen-awesome-css
37+
HTML_COLORSTYLE = LIGHT # required with Doxygen >= 1.9.5
38+
HTML_COLORSTYLE_HUE = 209
39+
HTML_COLORSTYLE_SAT = 255
40+
HTML_COLORSTYLE_GAMMA = 113
41+
HTML_COPY_CLIPBOARD = NO # required for Doxygen >= 1.10.0
42+
HTML_EXTRA_FILES = ../third-party/doxyconfig/doxygen-awesome-css/doxygen-awesome-darkmode-toggle.js
43+
HTML_EXTRA_FILES += ../third-party/doxyconfig/doxygen-awesome-css/doxygen-awesome-fragment-copy-button.js
44+
HTML_EXTRA_FILES += ../third-party/doxyconfig/doxygen-awesome-css/doxygen-awesome-paragraph-link.js
45+
HTML_EXTRA_FILES += ../third-party/doxyconfig/doxygen-awesome-css/doxygen-awesome-interactive-toc.js
46+
HTML_EXTRA_FILES += ../third-party/doxyconfig/doxygen-awesome-css/doxygen-awesome-tabs.js
47+
HTML_EXTRA_STYLESHEET = ../third-party/doxyconfig/doxygen-awesome-css/doxygen-awesome.css
48+
HTML_HEADER = header-doxyconfig.html
49+
50+
# custom aliases
51+
ALIASES = ""
52+
ALIASES += "examples=^^**Examples**^^@code{.cpp}"
53+
ALIASES += "examples_end=@endcode^^"
54+
# fontawsome
55+
ALIASES += "fa_icon{1}=<i class=\"\1\"></i>"
56+
# admonitions
57+
ALIASES += "_admonition{4|}=<dl class=\"\2\"><dt>@fa_icon{\3} \1</dt><dd>\4</dd></dl>"
58+
ALIASES += "_admonition_b{4|}=<dl class=\"\2\"><dt><b><a style=\"pointer-events: none; cursor: default;\" class=\"el\" href=\"\">@fa_icon{\3} \1</a></b></dt><dd>\4</dd></dl>"
59+
# see: https://jothepro.github.io/doxygen-awesome-css/class_my_library_1_1_example.html#autotoc_md6
60+
ALIASES += "admonition{2|}=@_admonition_b{\1 | todo | fa-solid fa-bars | \2}"
61+
ALIASES += "attention{1}=@_admonition{Attention | bug | fa-solid fa-triangle-exclamation | \1}"
62+
ALIASES += "caution{1}=@_admonition{Caution | section warning | fa-solid fa-triangle-exclamation | \1}"
63+
ALIASES += "danger{1}=@_admonition{Danger | bug | fa-solid fa-circle-exclamation | \1}"
64+
ALIASES += "error{1}=@_admonition{Error | bug | fa-solid fa-circle-xmark | \1}"
65+
ALIASES += "hint{1}=@_admonition{Hint | section pre | fa-solid fa-circle-question | \1}"
66+
ALIASES += "important{1}=@_admonition_b{Important | todo | fa-solid fa-fire | \1}"
67+
ALIASES += "note{1}=@_admonition{Note | section note | fa-solid fa-pencil | \1}"
68+
ALIASES += "seealso{1}=@_admonition{See also | section note | fa-solid fa-circle-info | \1}"
69+
ALIASES += "tip{1}=@_admonition{Tip | section pre | fa-solid fa-circle-info | \1}"
70+
ALIASES += "todo{1}=@_admonition{TODO | section deprecated | fa-solid fa-pencil | \1}"
71+
ALIASES += "warning{1}=@_admonition{Warning | section warning | fa-solid fa-triangle-exclamation | \1}"
72+
# tabs
73+
# see: https://github.com/jothepro/doxygen-awesome-css/discussions/146
74+
ALIASES += tab{2|}="@htmlonly<li><b class=\"tab-title\">@endhtmlonly^^\1^^@htmlonly</b>@endhtmlonly^^\2^^@htmlonly</li>@endhtmlonly"
75+
ALIASES += tabs{1}="@htmlonly<div class=\"tabbed\"><ul>@endhtmlonly^^\1^^@htmlonly</ul></div><br>@endhtmlonly"
76+
# markers
77+
ALIASES += red{1}="<span style=\"color:red\">\1</span>"
78+
ALIASES += blue{1}="<span style=\"color:blue\">\1</span>"
79+
ALIASES += green{1}="<span style=\"color:green\">\1</span>"
80+
ALIASES += yellow{1}="<span style=\"color:yellow\">\1</span>"
81+
# expander
82+
ALIASES += expander{2|}="@htmlonly<details><summary>^^\1^^</summary><div>@endhtmlonly^^\2^^@htmlonly</div></details>@endhtmlonly"
83+
84+
# common predefined
85+
PREDEFINED = DOXYGEN
86+
PREDEFINED += __APPLE__
87+
PREDEFINED += linux
88+
PREDEFINED += __linux
89+
PREDEFINED += __linux__
90+
PREDEFINED += __MACH__
91+
PREDEFINED += _WIN32
92+
93+
# general settings
94+
CASE_SENSE_NAMES = YES
95+
CREATE_SUBDIRS = NO
96+
DISABLE_INDEX = NO
97+
DOCBOOK_OUTPUT = docbook
98+
DOT_IMAGE_FORMAT = svg
99+
DOT_NUM_THREADS = 1
100+
EXTRACT_ALL = NO
101+
FULL_SIDEBAR = NO
102+
GENERATE_HTML = YES
103+
GENERATE_LATEX = NO
104+
GENERATE_TREEVIEW = YES
105+
GENERATE_XML = NO
106+
HAVE_DOT = YES
107+
HTML_OUTPUT = html
108+
INTERACTIVE_SVG = YES
109+
LATEX_OUTPUT = latex
110+
MACRO_EXPANSION = YES
111+
MAN_OUTPUT = man
112+
MARKDOWN_ID_STYLE = GITHUB
113+
MARKDOWN_SUPPORT = YES
114+
NUM_PROC_THREADS = 1
115+
PROJECT_NUMBER = $(READTHEDOCS_VERSION)
116+
OUTPUT_DIRECTORY = $(READTHEDOCS_OUTPUT)
117+
RECURSIVE = YES
118+
RTF_OUTPUT = rtf
119+
SORT_BRIEF_DOCS = YES
120+
STRIP_FROM_INC_PATH = ../
121+
STRIP_FROM_PATH = ../
122+
WARN_AS_ERROR = FAIL_ON_WARNINGS
123+
WARN_IF_DOC_ERROR = YES
124+
WARN_IF_INCOMPLETE_DOC = YES
125+
WARN_IF_UNDOC_ENUM_VAL = YES
126+
WARN_IF_UNDOCUMENTED = YES
127+
WARN_NO_PARAMDOC = YES
128+
WARNINGS = YES
129+
XML_OUTPUT = xml
130+
131+
# append the project specific settings here

‎README.md

Lines changed: 36 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,2 +1,36 @@
1-
# template-base
2-
Base repository template for LizardByte.
1+
# doxyconfig
2+
3+
This is a common Doxygen config for LizardByte projects.
4+
5+
## Usage
6+
7+
1. Add this repository as a submodule to your project.
8+
9+
```bash
10+
git submodule add https://github.com/LizardByte/doxyconfig.git third-party/doxyconfig
11+
```
12+
13+
2. Place project specific Doxyfile config in `./docs/Doxyfile`. You can overwrite anything from the common config here.
14+
3. Add the following to your CMakeLists.txt file.
15+
16+
```cmake
17+
option(BUILD_DOCS "Build documentation" ON)
18+
if(BUILD_DOCS)
19+
add_subdirectory(third-party/doxyconfig docs)
20+
endif()
21+
```
22+
23+
4. Add the following to your `.gitignore` file.
24+
25+
```gitignore
26+
# doxyconfig
27+
docs/*-doxyconfig*
28+
```
29+
30+
5. Optionally, add the following to the input list in your Doxyfile.
31+
32+
```doxyfile
33+
INPUT += ../third-party/doxyconfig/docs/source_code.md
34+
```
35+
36+
6. Optionally, copy the `.readthedocs.yaml` file to the root of your project.

0 commit comments

Comments
 (0)