Skip to content

Commit 7987894

Browse files
ReenigneArcherReenigneArcher
authored
docs: add readthedocs build (#3)
1 parent 671b494 commit 7987894

File tree

4 files changed

+110
-18
lines changed

4 files changed

+110
-18
lines changed

‎.readthedocs.yaml‎

Lines changed: 8 additions & 18 deletions
Original file line numberDiff line numberDiff line change
@@ -10,25 +10,15 @@ build:
1010
tools:
1111
python: "miniconda-latest"
1212
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/
2213
- |
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
14+
if [ -f readthedocs_build.sh ]; then
15+
doxyconfig_dir="."
16+
else
17+
doxyconfig_dir="./third-party/doxyconfig"
18+
fi
19+
chmod +x "${doxyconfig_dir}/readthedocs_build.sh"
20+
export DOXYCONFIG_DIR="${doxyconfig_dir}"
21+
"${doxyconfig_dir}/readthedocs_build.sh"
3222
3323
# using conda, we can get newer doxygen and graphviz than ubuntu provide
3424
# https://github.com/readthedocs/readthedocs.org/issues/8151#issuecomment-890359661

‎Doxyfile‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -95,6 +95,7 @@ CASE_SENSE_NAMES = YES
9595
CREATE_SUBDIRS = NO
9696
DISABLE_INDEX = NO
9797
DOCBOOK_OUTPUT = docbook
98+
DOT_GRAPH_MAX_NODES = 50
9899
DOT_IMAGE_FORMAT = svg
99100
DOT_NUM_THREADS = 1
100101
EXTRACT_ALL = NO

‎docs/Doxyfile‎

Lines changed: 35 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,35 @@
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+
# project metadata
25+
DOCSET_BUNDLE_ID = dev.lizardbyte.doxyconfig
26+
DOCSET_PUBLISHER_ID = dev.lizardbyte.doxyconfig.documentation
27+
PROJECT_BRIEF = "Common doxygen config for LizardByte projects."
28+
PROJECT_NAME = doxyconfig
29+
30+
# project specific settings
31+
32+
# files and directories to process
33+
USE_MDFILE_AS_MAINPAGE = ../README.md
34+
INPUT = ../README.md \
35+
source_code.md

‎readthedocs_build.sh‎

Lines changed: 66 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,66 @@
1+
#!/usr/bin/env bash
2+
set -e
3+
4+
function setup_conda_env {
5+
echo "Setting up conda environment"
6+
local environment_file="third-party/doxyconfig/environment.yml"
7+
8+
if [ "${DOXYCONFIG_DIR}" == "." ]; then
9+
mkdir -p third-party/doxyconfig
10+
cp environment.yml $environment_file
11+
cp -r doxygen-awesome-css third-party/doxyconfig/
12+
fi
13+
14+
echo "cat $environment_file"
15+
cat $environment_file
16+
17+
echo "conda env create --quiet --name ${READTHEDOCS_VERSION} --file $environment_file"
18+
conda env create --quiet --name "${READTHEDOCS_VERSION}" --file "$environment_file"
19+
}
20+
21+
function install_icons {
22+
echo "Downloading LizardByte graphics"
23+
wget "https://raw.githubusercontent.com/LizardByte/.github/master/branding/logos/favicon.ico" \
24+
-O "${READTHEDOCS_OUTPUT}lizardbyte.ico"
25+
wget "https://raw.githubusercontent.com/LizardByte/.github/master/branding/logos/logo-128x128.png" \
26+
-O "${READTHEDOCS_OUTPUT}lizardbyte.png"
27+
}
28+
29+
function install_node_modules {
30+
echo "Creating output directories"
31+
mkdir -p "${READTHEDOCS_OUTPUT}html/assets/fontawesome/css"
32+
mkdir -p "${READTHEDOCS_OUTPUT}html/assets/fontawesome/js"
33+
34+
echo "Installing node modules"
35+
pushd "${DOXYCONFIG_DIR}"
36+
npm install
37+
popd
38+
39+
echo "Copying FontAwesome files"
40+
cp "${DOXYCONFIG_DIR}/node_modules/@fortawesome/fontawesome-free/css/all.min.css" \
41+
"${READTHEDOCS_OUTPUT}html/assets/fontawesome/css"
42+
cp "${DOXYCONFIG_DIR}/node_modules/@fortawesome/fontawesome-free/js/all.min.js" \
43+
"${READTHEDOCS_OUTPUT}html/assets/fontawesome/js"
44+
cp -r "${DOXYCONFIG_DIR}/node_modules/@fortawesome/fontawesome-free/webfonts" \
45+
"${READTHEDOCS_OUTPUT}html/assets/fontawesome/"
46+
}
47+
48+
function merge_doxyconfigs {
49+
echo "Merging doxygen configs"
50+
cp "${DOXYCONFIG_DIR}/Doxyfile" "./docs/Doxyfile-doxyconfig"
51+
cp "${DOXYCONFIG_DIR}/header.html" "./docs/header-doxyconfig.html"
52+
cat "./docs/Doxyfile" >> "./docs/Doxyfile-doxyconfig"
53+
}
54+
55+
function build_docs {
56+
echo "Building docs"
57+
pushd docs
58+
doxygen Doxyfile-doxyconfig
59+
popd
60+
}
61+
62+
setup_conda_env
63+
install_node_modules
64+
install_icons
65+
merge_doxyconfigs
66+
build_docs

0 commit comments

Comments
 (0)