docs: add readthedocs build (#3)

.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

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

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

readthedocs_build.sh

@@ -0,0 +1,66 @@
+#!/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
+    cp -r doxygen-awesome-css third-party/doxyconfig/
+  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