Add PRESERVE_FOLDERS feature to documentation generation script

This change allows preserving specified folders (like webserial interfaces)
during documentation generation. Folders specified in the PRESERVE_FOLDERS
environment variable will be backed up before cleanup and restored afterward.

- Added PRESERVE_FOLDERS environment variable support
- Updated README with documentation and example usage

README.md

@@ -76,3 +76,18 @@ The `doxy_gen_and_deploy.sh` script uses [Doxygen](https://www.doxygen.nl/) to g
 for the library. Any issues, like missing documentation, will cause the CI to fail.
 See the [guide](https://learn.adafruit.com/the-well-automated-arduino-library/doxygen) for details on installing and running Doxygen locally. The guide also has some
 [tips](https://learn.adafruit.com/the-well-automated-arduino-library/doxygen-tips) on basic usage of Doxygen markup within your code.
+
+### Preserving Folders in Documentation Branch
+
+By default, the documentation deployment script cleans the gh-pages branch before adding new documentation. If you need to preserve certain folders (like custom web interfaces), you can set the `PRESERVE_FOLDERS` environment variable in your workflow:
+
+```yaml
+- name: doxygen
+  env:
+    GH_REPO_TOKEN: ${{ secrets.GH_REPO_TOKEN }}
+    PRETTYNAME : "My Arduino Library"
+    PRESERVE_FOLDERS: "webserial,assets"
+  run: bash ci/doxy_gen_and_deploy.sh
+```
+
+This will preserve the listed folders (comma-separated) during the documentation generation process.

doxy_gen_and_deploy.sh

@@ -18,6 +18,7 @@ __AUTHOR__="Jeroen de Bruijn, modified by ladyada"
 # Optional global variables:
 # - DOXYFILE            : The Doxygen configuration file.
 # - PRETTYNAME          : A string name of the project (for the doxy headers)
+# - PRESERVE_FOLDERS    : Comma-separated list of folders to preserve during cleanup
 #
 # For information on how to encrypt variables for Travis CI please go to
 # https://docs.travis-ci.com/user/environment-variables/#Encrypted-Variables
@@ -84,6 +85,19 @@ git config --global push.default simple
 git config user.name "Doxygen CI"
 git config user.email "ci-arduino@invalid"
 
+# Check if PRESERVE_FOLDERS is set and back them up
+if [ -n "$PRESERVE_FOLDERS" ]; then
+  echo "Preserving folders: $PRESERVE_FOLDERS"
+  mkdir -p /tmp/preserved
+  # Move preserved folders to temp dir
+  for folder in ${PRESERVE_FOLDERS//,/ }; do
+    if [ -d "$folder" ]; then
+      echo "Backing up folder: $folder"
+      cp -r "$folder" /tmp/preserved/
+    fi
+  done
+fi
+
 # Remove everything currently in the gh-pages branch.
 # GitHub is smart enough to know which files have changed and which files have
 # stayed the same and will only update the changed files. So the gh-pages branch
@@ -99,6 +113,16 @@ else
     rm -r -- !(index.html) || true
 fi
 
+# Restore preserved folders if they were backed up
+if [ -n "$PRESERVE_FOLDERS" ]; then
+  for folder in ${PRESERVE_FOLDERS//,/ }; do
+    if [ -d "/tmp/preserved/$folder" ]; then
+      echo "Restoring folder: $folder"
+      cp -r "/tmp/preserved/$folder" ./
+    fi
+  done
+fi
+
 # Need to create a .nojekyll file to allow filenames starting with an underscore
 # to be seen on the gh-pages site. Therefore creating an empty .nojekyll file.
 # Presumably this is only needed when the SHORT_NAMES option in Doxygen is set