Dox not building when using src folder

[Carter Nelson]

For libraries that put code in a src folder, ex:
https://github.com/adafruit/Adafruit_VL53L1X
the doxygen output is not generated if using default configurations for everything. There is output, but it is empty:
https://adafruit.github.io/Adafruit_VL53L1X/html/index.html

This happens because the default workflow calls doxygen without any additional command line arguments:
https://github.com/adafruit/Adafruit_VL53L1X/blob/6353b69c1de9ed9de0a2187745074d1cdee4071c/.github/workflows/githubci.yml#L33
so it ends up looking for source in the root repo folder.

Two possible fixes?

OPTION 1
Per repo fix of .github/workflows/githubci.yml to add src (or whatever) to specify folder. Ex:

      run: bash ci/doxy_gen_and_deploy.sh src

This works since the script has a check for this:

ci-arduino/doxy_gen_and_deploy.sh

Lines 129 to 136 in e659722

 if [ ! -z $1 ] 
 then 
     # Print out doxygen warnings in red, use specified path (for when everything is in src) 
     ( cat $DOXYFILE; echo "INPUT=${BUILD_DIR}/$1" ) | ${BUILD_DIR}/doxygen - 2>&1 | tee foo.txt > >(while read line; do echo -e "\e[01;31m$line\e[0m" >&2; done) 
 else 
     # Print out doxygen warnings in red, use default path 
     ${BUILD_DIR}/doxygen $DOXYFILE 2>&1 | tee foo.txt > >(while read line; do echo -e "\e[01;31m$line\e[0m" >&2; done) 
 fi 

OPTION 2
If no path specified (current default), then alter doxy_gen_and_deploy.sh script to automatically check for existence of src folder and, if found, set that as INPUT= location.

[Limor "Ladyada" Fried]

yeah i usually dont do src/ folders and if i do it usually needs a custom doxy anyways. i think best to update the shell script to look in both spots - are you up for doing that change?

[Carter Nelson]

sure. can at least PR something :)

[Limor "Ladyada" Fried]

ok btw we dont doxy non-adafruit files because we want to make catch-up upstream merges clean, so im still thinking this wont work as-is because there'll be extra files, but its ok to try!

[Carter Nelson]

So using the VL53L1X library as example, you'd only want to dox Adafruit_VL53L1X.* and skip all others?

If files follow a practice of prefixing with Adafruit_, could make it doable? More logic in the script? Wildcard filter for doxy config? (not sure at this point)

[Limor "Ladyada" Fried]

thats the thing, it is so weirdly dependant, i just copy over a Doxyfile and edit the file listing in it
https://github.com/adafruit/Adafruit_VL53L0X/blob/master/doxyfile

[Carter Nelson]

Ah, an Option 3 - add a per repo custom doxyfile? That'd fix it and not require any attempts to fancy up the CI logic in the scripts. Want to just do that for now? Or worth trying to update the Ci to be fancier?

[Limor "Ladyada" Fried]

tahts what i do for 'weird' repos already, there's a default doxyfile used when one isnt committed to the repo

[Carter Nelson]

Cool. That'll work. Closing this then, since no changes needed here.

Solution TLDR = add custom Doxyfile to override default and explicitly specify sources there