electronics
/
libopencm3
9
0
Fork 0
Code Issues Pull Requests Projects Releases Wiki Activity
libopencm3/scripts/gendoxylist

30 lines
1.2 KiB
Plaintext
Raw Permalink Normal View History

doc: dynamically generate correct file lists Instead of the fragile and error prone attempts to specifically include/exclude files from doxygen by name and pattern, simply use the already generated .d files to provide accurate and up to date lists of all source files used. Pros: * Nothing left to worry about * Much more encouraging to actually _work_ on the documentation now that you can be sure the right docs will be generated instead of a confusing mix. Downsides/Upsides: * Automatically includes all CM3/USB in each device's page _as well_ now Downsides: * lpc43xx still manually listed. However, completely contained in it's own dir, so no problems * No attempt to carry this in latex. easy, but more tempted to drop latex support outright. (I don't think the generation there has even worked for a while now) * Due to the mismatch between lib directories and document roots, the sourcelist can't be magically created per directory. There has to be some sort of mapping between the two, so as this is doc generation only, a static list seems sane for maintennance. (Especially compared to the old method) * Source list generation probably doesn't work on windows.
2017-10-04 22:09:04 +00:00
#!/bin/sh
# Karl Palsson <karlp@tweak.net.au> Sept 2017
# Parse .d files for a given target, and generate a doxygen config file
# stub that is to be "@INCLUDE = <xxx>" into a doxygen template file.
gendoxylist: make it not "crash" if you try interactively at least
2020-11-27 21:08:38 +00:00
[ $# -eq 2 ] || {
printf "Usage: $0 <libdir> <outputdir>\n"
exit 1
}
doc: dynamically generate correct file lists Instead of the fragile and error prone attempts to specifically include/exclude files from doxygen by name and pattern, simply use the already generated .d files to provide accurate and up to date lists of all source files used. Pros: * Nothing left to worry about * Much more encouraging to actually _work_ on the documentation now that you can be sure the right docs will be generated instead of a confusing mix. Downsides/Upsides: * Automatically includes all CM3/USB in each device's page _as well_ now Downsides: * lpc43xx still manually listed. However, completely contained in it's own dir, so no problems * No attempt to carry this in latex. easy, but more tempted to drop latex support outright. (I don't think the generation there has even worked for a while now) * Due to the mismatch between lib directories and document roots, the sourcelist can't be magically created per directory. There has to be some sort of mapping between the two, so as this is doc generation only, a static list seems sane for maintennance. (Especially compared to the old method) * Source list generation probably doesn't work on windows.
2017-10-04 22:09:04 +00:00
DDIR=$1
ODIR=$2
ONAME=doxy.sourcelist
doxygen: include all target headers Even if they haven't been referenced from a .c file. Some peripherals start their life as register definitions only, and they should still have the documentation generated. There _will_ be overlap in the generated lists, but doxygen doesn't seem to mind this.
2017-10-23 20:58:04 +00:00
IPATH=$(echo ${DDIR} | sed -e 's#../lib/##')
doc: dynamically generate correct file lists Instead of the fragile and error prone attempts to specifically include/exclude files from doxygen by name and pattern, simply use the already generated .d files to provide accurate and up to date lists of all source files used. Pros: * Nothing left to worry about * Much more encouraging to actually _work_ on the documentation now that you can be sure the right docs will be generated instead of a confusing mix. Downsides/Upsides: * Automatically includes all CM3/USB in each device's page _as well_ now Downsides: * lpc43xx still manually listed. However, completely contained in it's own dir, so no problems * No attempt to carry this in latex. easy, but more tempted to drop latex support outright. (I don't think the generation there has even worked for a while now) * Due to the mismatch between lib directories and document roots, the sourcelist can't be magically created per directory. There has to be some sort of mapping between the two, so as this is doc generation only, a static list seems sane for maintennance. (Especially compared to the old method) * Source list generation probably doesn't work on windows.
2017-10-04 22:09:04 +00:00
PATH_DELTA=$(realpath --relative-to=${ODIR} ${DDIR})
printf "# This file is autogenerated by scripts/gendoxylist\n" > ${ODIR}/${ONAME}
doc: make sure include/cm3 is pulled in properly. Much as we had to pull in the individual target's include files manually, because they're useful without necessarily having .c files using them, the cortex core headers also need to be included. This also pulls in the doc-cm3.h file that setup nice groupings.
2018-09-09 15:11:23 +00:00
printf "# All headers for core/platform, not always caught by .d file tracking\n" >> ${ODIR}/${ONAME}
UNTRACKED_DIRS="../include/libopencm3/cm3 ../include/libopencm3/${IPATH}"
gendoxylist: sort headers This makes the doxygen lists much more rationally ordered.
2019-06-25 12:36:29 +00:00
for FN in $(find ${UNTRACKED_DIRS} -name '*.h' | sort); do
doxygen: include all target headers Even if they haven't been referenced from a .c file. Some peripherals start their life as register definitions only, and they should still have the documentation generated. There _will_ be overlap in the generated lists, but doxygen doesn't seem to mind this.
2017-10-23 20:58:04 +00:00
printf "INPUT += ../%s\n" "$FN" >> ${ODIR}/${ONAME}
done
doc: dynamically generate correct file lists Instead of the fragile and error prone attempts to specifically include/exclude files from doxygen by name and pattern, simply use the already generated .d files to provide accurate and up to date lists of all source files used. Pros: * Nothing left to worry about * Much more encouraging to actually _work_ on the documentation now that you can be sure the right docs will be generated instead of a confusing mix. Downsides/Upsides: * Automatically includes all CM3/USB in each device's page _as well_ now Downsides: * lpc43xx still manually listed. However, completely contained in it's own dir, so no problems * No attempt to carry this in latex. easy, but more tempted to drop latex support outright. (I don't think the generation there has even worked for a while now) * Due to the mismatch between lib directories and document roots, the sourcelist can't be magically created per directory. There has to be some sort of mapping between the two, so as this is doc generation only, a static list seems sane for maintennance. (Especially compared to the old method) * Source list generation probably doesn't work on windows.
2017-10-04 22:09:04 +00:00
doxygen: include all target headers Even if they haven't been referenced from a .c file. Some peripherals start their life as register definitions only, and they should still have the documentation generated. There _will_ be overlap in the generated lists, but doxygen doesn't seem to mind this.
2017-10-23 20:58:04 +00:00
# There will be duplicates here, but doxygen doesn't mind.
doc: dynamically generate correct file lists Instead of the fragile and error prone attempts to specifically include/exclude files from doxygen by name and pattern, simply use the already generated .d files to provide accurate and up to date lists of all source files used. Pros: * Nothing left to worry about * Much more encouraging to actually _work_ on the documentation now that you can be sure the right docs will be generated instead of a confusing mix. Downsides/Upsides: * Automatically includes all CM3/USB in each device's page _as well_ now Downsides: * lpc43xx still manually listed. However, completely contained in it's own dir, so no problems * No attempt to carry this in latex. easy, but more tempted to drop latex support outright. (I don't think the generation there has even worked for a while now) * Due to the mismatch between lib directories and document roots, the sourcelist can't be magically created per directory. There has to be some sort of mapping between the two, so as this is doc generation only, a static list seems sane for maintennance. (Especially compared to the old method) * Source list generation probably doesn't work on windows.
2017-10-04 22:09:04 +00:00
printf "# Headers first\n" >> ${ODIR}/${ONAME}
grep -o '[^ ]*.h' ${DDIR}/*.d | grep 'include/libopencm3' | cut -d ':' -f2 | sort | uniq | sed "s#^#INPUT += ${PATH_DELTA}/#" >> ${ODIR}/${ONAME}
printf "# Now sources\n" >> ${ODIR}/${ONAME}
grep -o '[^ ]*\.c' ${DDIR}/*.d | cut -d ':' -f 2 | sort | uniq | sed "s#^#INPUT += $PATH_DELTA/#" >> ${ODIR}/${ONAME}