diff --git a/README.md b/README.md index 9cdc737..1401bb5 100644 --- a/README.md +++ b/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. diff --git a/doxy_gen_and_deploy.sh b/doxy_gen_and_deploy.sh index 21264ca..23b6039 100755 --- a/doxy_gen_and_deploy.sh +++ b/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