diff --git a/.readthedocs.yaml b/.readthedocs.yaml index a2c132d..ee2f3bb 100644 --- a/.readthedocs.yaml +++ b/.readthedocs.yaml @@ -10,25 +10,15 @@ build: tools: python: "miniconda-latest" commands: - # because we are overriding the build commands, we need to setup the environment ourselves - - cat third-party/doxyconfig/environment.yml - - conda env create --quiet --name ${READTHEDOCS_VERSION} --file third-party/doxyconfig/environment.yml - - npm install "@fortawesome/fontawesome-free" - - mkdir -p ${READTHEDOCS_OUTPUT}html/assets/fontawesome/css - - mkdir -p ${READTHEDOCS_OUTPUT}html/assets/fontawesome/js - - cp node_modules/@fortawesome/fontawesome-free/css/all.min.css ${READTHEDOCS_OUTPUT}html/assets/fontawesome/css - - cp node_modules/@fortawesome/fontawesome-free/js/all.min.js ${READTHEDOCS_OUTPUT}html/assets/fontawesome/js - - cp -r node_modules/@fortawesome/fontawesome-free/webfonts ${READTHEDOCS_OUTPUT}html/assets/fontawesome/ - | - wget "https://raw.githubusercontent.com/LizardByte/.github/master/branding/logos/favicon.ico" \ - -O ${READTHEDOCS_OUTPUT}lizardbyte.ico - - | - wget "https://raw.githubusercontent.com/LizardByte/.github/master/branding/logos/logo-128x128.png" \ - -O ${READTHEDOCS_OUTPUT}lizardbyte.png - - cp ./third-party/doxyconfig/Doxyfile ./docs/Doxyfile-doxyconfig - - cp ./third-party/doxyconfig/header.html ./docs/header-doxyconfig.html - - cat ./docs/Doxyfile >> ./docs/Doxyfile-doxyconfig - - cd docs && doxygen Doxyfile-doxyconfig + if [ -f readthedocs_build.sh ]; then + doxyconfig_dir="." + else + doxyconfig_dir="./third-party/doxyconfig" + fi + chmod +x "${doxyconfig_dir}/readthedocs_build.sh" + export DOXYCONFIG_DIR="${doxyconfig_dir}" + "${doxyconfig_dir}/readthedocs_build.sh" # using conda, we can get newer doxygen and graphviz than ubuntu provide # https://github.com/readthedocs/readthedocs.org/issues/8151#issuecomment-890359661 diff --git a/Doxyfile b/Doxyfile index 2cbfa1b..c0dffc2 100644 --- a/Doxyfile +++ b/Doxyfile @@ -95,6 +95,7 @@ CASE_SENSE_NAMES = YES CREATE_SUBDIRS = NO DISABLE_INDEX = NO DOCBOOK_OUTPUT = docbook +DOT_GRAPH_MAX_NODES = 50 DOT_IMAGE_FORMAT = svg DOT_NUM_THREADS = 1 EXTRACT_ALL = NO diff --git a/docs/Doxyfile b/docs/Doxyfile new file mode 100644 index 0000000..cbaa6d4 --- /dev/null +++ b/docs/Doxyfile @@ -0,0 +1,35 @@ +# This file describes the settings to be used by the documentation system +# doxygen (www.doxygen.org) for a project. +# +# All text after a double hash (##) is considered a comment and is placed in +# front of the TAG it is preceding. +# +# All text after a single hash (#) is considered a comment and will be ignored. +# The format is: +# TAG = value [value, ...] +# For lists, items can also be appended using: +# TAG += value [value, ...] +# Values that contain spaces should be placed between quotes (\" \"). +# +# Note: +# +# Use doxygen to compare the used configuration file with the template +# configuration file: +# doxygen -x [configFile] +# Use doxygen to compare the used configuration file with the template +# configuration file without replacing the environment variables or CMake type +# replacement variables: +# doxygen -x_noenv [configFile] + +# project metadata +DOCSET_BUNDLE_ID = dev.lizardbyte.doxyconfig +DOCSET_PUBLISHER_ID = dev.lizardbyte.doxyconfig.documentation +PROJECT_BRIEF = "Common doxygen config for LizardByte projects." +PROJECT_NAME = doxyconfig + +# project specific settings + +# files and directories to process +USE_MDFILE_AS_MAINPAGE = ../README.md +INPUT = ../README.md \ + source_code.md \ diff --git a/readthedocs_build.sh b/readthedocs_build.sh new file mode 100644 index 0000000..fecdd63 --- /dev/null +++ b/readthedocs_build.sh @@ -0,0 +1,65 @@ +#!/usr/bin/env bash +set -e + +function setup_conda_env { + echo "Setting up conda environment" + local environment_file="third-party/doxyconfig/environment.yml" + + if [ "${DOXYCONFIG_DIR}" == "." ]; then + mkdir -p third-party/doxyconfig + cp environment.yml $environment_file + fi + + echo "cat $environment_file" + cat $environment_file + + echo "conda env create --quiet --name ${READTHEDOCS_VERSION} --file $environment_file" + conda env create --quiet --name "${READTHEDOCS_VERSION}" --file "$environment_file" +} + +function install_icons { + echo "Downloading LizardByte graphics" + wget "https://raw.githubusercontent.com/LizardByte/.github/master/branding/logos/favicon.ico" \ + -O "${READTHEDOCS_OUTPUT}lizardbyte.ico" + wget "https://raw.githubusercontent.com/LizardByte/.github/master/branding/logos/logo-128x128.png" \ + -O "${READTHEDOCS_OUTPUT}lizardbyte.png" +} + +function install_node_modules { + echo "Creating output directories" + mkdir -p "${READTHEDOCS_OUTPUT}html/assets/fontawesome/css" + mkdir -p "${READTHEDOCS_OUTPUT}html/assets/fontawesome/js" + + echo "Installing node modules" + pushd "${DOXYCONFIG_DIR}" + npm install + popd + + echo "Copying FontAwesome files" + cp "${DOXYCONFIG_DIR}/node_modules/@fortawesome/fontawesome-free/css/all.min.css" \ + "${READTHEDOCS_OUTPUT}html/assets/fontawesome/css" + cp "${DOXYCONFIG_DIR}/node_modules/@fortawesome/fontawesome-free/js/all.min.js" \ + "${READTHEDOCS_OUTPUT}html/assets/fontawesome/js" + cp -r "${DOXYCONFIG_DIR}/node_modules/@fortawesome/fontawesome-free/webfonts" \ + "${READTHEDOCS_OUTPUT}html/assets/fontawesome/" +} + +function merge_doxyconfigs { + echo "Merging doxygen configs" + cp "${DOXYCONFIG_DIR}/Doxyfile" "./docs/Doxyfile-doxyconfig" + cp "${DOXYCONFIG_DIR}/header.html" "./docs/header-doxyconfig.html" + cat "./docs/Doxyfile" >> "./docs/Doxyfile-doxyconfig" +} + +function build_docs { + echo "Building docs" + pushd docs + doxygen Doxyfile-doxyconfig + popd +} + +setup_conda_env +install_node_modules +install_icons +merge_doxyconfigs +build_docs