jackcartersmith/blackmagic
1
0
Fork 0
Code Issues Pull Requests Releases Activity

doc: dynamically generate correct file lists

Browse Source 
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.
This commit is contained in:
Karl Palsson 2017-10-04 22:09:04 +00:00
parent f592e6d54e
commit d002d9552f
25 changed files with 97 additions and 224 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

1
.gitignore vendored
View File

@ -25,6 +25,7 @@ include/libopencm3/**/nvic.h
include/libopencm3/**/**/nvic.h include/libopencm3/**/**/nvic.h
lib/**/vector_nvic.c lib/**/vector_nvic.c
lib/**/**/vector_nvic.c lib/**/**/vector_nvic.c
doxy.sourcelist
include/libopencmsis/efm32/ include/libopencmsis/efm32/
include/libopencmsis/lm3s/ include/libopencmsis/lm3s/
include/libopencmsis/lpc13xx/ include/libopencmsis/lpc13xx/

31
doc/Makefile
View File

@ -15,7 +15,7 @@ PDFS := $(ARCHS:=.pdf)
doc: html latex doc: html latex
html: cm3 usb $(ARCHS) html: rebuildsources cm3 usb $(ARCHS)
doxygen doxygen
latex: $(PDFS) latex: $(PDFS)
@ -35,5 +35,32 @@ $(ARCHS):
clean: clean:
@rm -rf html/ */html/ */latex/ *.pdf */*.tag @rm -rf html/ */html/ */latex/ *.pdf */*.tag
.PHONY: doc html cm3 usb $(ARCHS) latex rebuildsources:
@printf "Manually regenerating source lists from build deps\n"
../scripts/gendoxylist ../lib/stm32/f0 stm32f0
../scripts/gendoxylist ../lib/stm32/f1 stm32f1
../scripts/gendoxylist ../lib/stm32/f2 stm32f2
../scripts/gendoxylist ../lib/stm32/f3 stm32f3
../scripts/gendoxylist ../lib/stm32/f4 stm32f4
../scripts/gendoxylist ../lib/stm32/f7 stm32f7
../scripts/gendoxylist ../lib/stm32/l0 stm32l0
../scripts/gendoxylist ../lib/stm32/l1 stm32l1
../scripts/gendoxylist ../lib/stm32/l4 stm32l4
../scripts/gendoxylist ../lib/stm32/l4 stm32l4
../scripts/gendoxylist ../lib/efm32/g efm32g
../scripts/gendoxylist ../lib/efm32/gg efm32gg
../scripts/gendoxylist ../lib/efm32/lg efm32lg
../scripts/gendoxylist ../lib/efm32/tg efm32tg
../scripts/gendoxylist ../lib/lm3s lm3s
../scripts/gendoxylist ../lib/lm4f lm4f
../scripts/gendoxylist ../lib/lpc13xx lpc13xx
../scripts/gendoxylist ../lib/lpc17xx lpc17xx
../scripts/gendoxylist ../lib/sam/3a sam3a
../scripts/gendoxylist ../lib/sam/3n sam3n
../scripts/gendoxylist ../lib/sam/3s sam3s
../scripts/gendoxylist ../lib/sam/3u sam3u
../scripts/gendoxylist ../lib/sam/3x sam3x
../scripts/gendoxylist ../lib/vf6xx vf6xx
.PHONY: doc html cm3 usb $(ARCHS) latex rebuildsources

7
doc/efm32g/Doxyfile
View File

@ -15,11 +15,8 @@
WARN_LOGFILE = doxygen_efm32g.log WARN_LOGFILE = doxygen_efm32g.log
INPUT = ../../include/libopencm3/license.dox \ INPUT = ../../include/libopencm3/license.dox
../../include/libopencm3/efm32/efm32g \ @INCLUDE = doxy.sourcelist
../../lib/efm32/efm32g
EXCLUDE =
LAYOUT_FILE = DoxygenLayout_efm32g.xml LAYOUT_FILE = DoxygenLayout_efm32g.xml

7
doc/efm32gg/Doxyfile
View File

@ -15,11 +15,8 @@
WARN_LOGFILE = doxygen_efm32gg.log WARN_LOGFILE = doxygen_efm32gg.log
INPUT = ../../include/libopencm3/license.dox \ INPUT = ../../include/libopencm3/license.dox
../../include/libopencm3/efm32/efm32gg \ @INCLUDE = doxy.sourcelist
../../lib/efm32/efm32gg
EXCLUDE =
LAYOUT_FILE = DoxygenLayout_efm32gg.xml LAYOUT_FILE = DoxygenLayout_efm32gg.xml

7
doc/efm32lg/Doxyfile
View File

@ -15,11 +15,8 @@
WARN_LOGFILE = doxygen_efm32lg.log WARN_LOGFILE = doxygen_efm32lg.log
INPUT = ../../include/libopencm3/license.dox \ INPUT = ../../include/libopencm3/license.dox
../../include/libopencm3/efm32/efm32lg \ @INCLUDE = doxy.sourcelist
../../lib/efm32/efm32lg
EXCLUDE =
LAYOUT_FILE = DoxygenLayout_efm32lg.xml LAYOUT_FILE = DoxygenLayout_efm32lg.xml

7
doc/efm32tg/Doxyfile
View File

@ -15,11 +15,8 @@
WARN_LOGFILE = doxygen_efm32tg.log WARN_LOGFILE = doxygen_efm32tg.log
INPUT = ../../include/libopencm3/license.dox \ INPUT = ../../include/libopencm3/license.dox
../../include/libopencm3/efm32/efm32tg \ @INCLUDE = doxy.sourcelist
../../lib/efm32/efm32tg
EXCLUDE =
LAYOUT_FILE = DoxygenLayout_efm32tg.xml LAYOUT_FILE = DoxygenLayout_efm32tg.xml

5
doc/lm3s/Doxyfile
View File

@ -15,9 +15,8 @@
WARN_LOGFILE = doxygen_lm3s.log WARN_LOGFILE = doxygen_lm3s.log
INPUT = ../../include/libopencm3/license.dox \ INPUT = ../../include/libopencm3/license.dox
../../include/libopencm3/lm3s \ @INCLUDE = doxy.sourcelist
../../lib/lm3s
LAYOUT_FILE = DoxygenLayout_lm3s.xml LAYOUT_FILE = DoxygenLayout_lm3s.xml

5
doc/lm4f/Doxyfile
View File

@ -15,9 +15,8 @@
WARN_LOGFILE = doxygen_lm4f.log WARN_LOGFILE = doxygen_lm4f.log
INPUT = ../../include/libopencm3/license.dox \ INPUT = ../../include/libopencm3/license.dox
../../include/libopencm3/lm4f \ @INCLUDE = doxy.sourcelist
../../lib/lm4f
LAYOUT_FILE = DoxygenLayout_lm4f.xml LAYOUT_FILE = DoxygenLayout_lm4f.xml

5
doc/lpc13xx/Doxyfile
View File

@ -15,9 +15,8 @@
WARN_LOGFILE = doxygen_lpc13xx.log WARN_LOGFILE = doxygen_lpc13xx.log
INPUT = ../../include/libopencm3/license.dox \ INPUT = ../../include/libopencm3/license.dox
../../include/libopencm3/lpc13xx \ @INCLUDE = doxy.sourcelist
../../lib/lpc13xx
LAYOUT_FILE = DoxygenLayout_lpc13xx.xml LAYOUT_FILE = DoxygenLayout_lpc13xx.xml

6
doc/lpc43xx/Doxyfile
View File

@ -15,9 +15,9 @@
WARN_LOGFILE = doxygen_lpc43xx.log WARN_LOGFILE = doxygen_lpc43xx.log
INPUT = ../../include/libopencm3/license.dox \ INPUT = ../../include/libopencm3/license.dox
../../include/libopencm3/lpc43xx \ INPUT += ../../include/libopencm3/lpc43xx
../../lib/lpc43xx INPUT += ../../lib/lpc43xx
LAYOUT_FILE = DoxygenLayout_lpc43xx.xml LAYOUT_FILE = DoxygenLayout_lpc43xx.xml

12
doc/sam3a/Doxyfile
View File

@ -17,16 +17,8 @@
WARN_LOGFILE = doxygen_sam3a.log WARN_LOGFILE = doxygen_sam3a.log
INPUT = ../../include/libopencm3/license.dox \ INPUT = ../../include/libopencm3/license.dox
../../include/libopencm3/sam/3a \ @INCLUDE = doxy.sourcelist
../../include/libopencm3/sam/common
INPUT += ../../lib/sam/3a \
../../lib/sam/common
EXCLUDE =
EXCLUDE_PATTERNS = *_common_3n3s.h
LAYOUT_FILE = DoxygenLayout_sam3a.xml LAYOUT_FILE = DoxygenLayout_sam3a.xml

12
doc/sam3n/Doxyfile
View File

@ -17,16 +17,8 @@
WARN_LOGFILE = doxygen_sam3n.log WARN_LOGFILE = doxygen_sam3n.log
INPUT = ../../include/libopencm3/license.dox \ INPUT = ../../include/libopencm3/license.dox
../../include/libopencm3/sam/3n \ @INCLUDE = doxy.sourcelist
../../include/libopencm3/sam/common
INPUT += ../../lib/sam/3n \
../../lib/sam/common
EXCLUDE =
EXCLUDE_PATTERNS = *_common_3a3u3x.h
LAYOUT_FILE = DoxygenLayout_sam3n.xml LAYOUT_FILE = DoxygenLayout_sam3n.xml

12
doc/sam3s/Doxyfile
View File

@ -17,16 +17,8 @@
WARN_LOGFILE = doxygen_sam3s.log WARN_LOGFILE = doxygen_sam3s.log
INPUT = ../../include/libopencm3/license.dox \ INPUT = ../../include/libopencm3/license.dox
../../include/libopencm3/sam/3s \ @INCLUDE = doxy.sourcelist
../../include/libopencm3/sam/common
INPUT += ../../lib/sam/3a \
../../lib/sam/common
EXCLUDE =
EXCLUDE_PATTERNS = *_common_3a3u3x.h
LAYOUT_FILE = DoxygenLayout_sam3s.xml LAYOUT_FILE = DoxygenLayout_sam3s.xml

12
doc/sam3u/Doxyfile
View File

@ -17,16 +17,8 @@
WARN_LOGFILE = doxygen_sam3u.log WARN_LOGFILE = doxygen_sam3u.log
INPUT = ../../include/libopencm3/license.dox \ INPUT = ../../include/libopencm3/license.dox
../../include/libopencm3/sam/3u \ @INCLUDE = doxy.sourcelist
../../include/libopencm3/sam/common
INPUT += ../../lib/sam/3u \
../../lib/sam/common
EXCLUDE =
EXCLUDE_PATTERNS = *_common_3n3s.h
LAYOUT_FILE = DoxygenLayout_sam3u.xml LAYOUT_FILE = DoxygenLayout_sam3u.xml

12
doc/sam3x/Doxyfile
View File

@ -17,16 +17,8 @@
WARN_LOGFILE = doxygen_sam3x.log WARN_LOGFILE = doxygen_sam3x.log
INPUT = ../../include/libopencm3/license.dox \ INPUT = ../../include/libopencm3/license.dox
../../include/libopencm3/sam/3x \ @INCLUDE = doxy.sourcelist
../../include/libopencm3/sam/common
INPUT += ../../lib/sam/3x \
../../lib/sam/common
EXCLUDE =
EXCLUDE_PATTERNS = *_common_3n3s.h
LAYOUT_FILE = DoxygenLayout_sam3x.xml LAYOUT_FILE = DoxygenLayout_sam3x.xml

17
doc/stm32f0/Doxyfile
View File

@ -1,4 +1,4 @@
# HTML Documentation for STM32F1 code level # HTML Documentation for STM32F0 code level
# 14 September 2012 # 14 September 2012
# (C) Ken Sarkies <ksarkies@internode.on.net> # (C) Ken Sarkies <ksarkies@internode.on.net>
@ -15,19 +15,8 @@
WARN_LOGFILE = doxygen_stm32f0.log WARN_LOGFILE = doxygen_stm32f0.log
INPUT = ../../include/libopencm3/license.dox \ INPUT = ../../include/libopencm3/license.dox
../../include/libopencm3/stm32/f0 \ @INCLUDE = doxy.sourcelist
../../include/libopencm3/stm32/common
INPUT += ../../lib/stm32/f0 \
../../lib/stm32/common
EXCLUDE = ../../include/libopencm3/stm32/f0/usb.h \
../../include/libopencm3/stm32/f0/usb_desc.h
EXCLUDE_PATTERNS = *_common_*f24.h *_common_*f24.c \
*_common_*f234.h *_common_*f234.c \
*_common_*f124.h *_common_*f124.c
LAYOUT_FILE = DoxygenLayout_stm32f0.xml LAYOUT_FILE = DoxygenLayout_stm32f0.xml

23
doc/stm32f1/Doxyfile
View File

@ -15,27 +15,8 @@
WARN_LOGFILE = doxygen_stm32f1.log WARN_LOGFILE = doxygen_stm32f1.log
INPUT = ../../include/libopencm3/license.dox \ INPUT = ../../include/libopencm3/license.dox
../../include/libopencm3/stm32/f1 \ @INCLUDE = doxy.sourcelist
../../include/libopencm3/stm32/common
INPUT += ../../lib/stm32/f1 \
../../lib/stm32/common
EXCLUDE = ../../include/libopencm3/stm32/f1/usb.h \
../../include/libopencm3/stm32/f1/usb_desc.h \
../../include/libopencm3/stm32/common/crs_common_all.h
EXCLUDE += ../../lib/stm32/common/crs_common_all.c \
../../lib/stm32/common/rtc_common_l1f024.c \
../../lib/stm32/common/
EXCLUDE_PATTERNS = *_common_*f24.h *_common_*f24.c \
*_common_*f234.h *_common_*f234.c \
*_common_*f0234.h *_common_*f0234.c \
*_common_*f024.h *_common_*f024.c \
*_common_*f03.h *_common_*f03.c \
*_common_l01.h _common_l01.c
LAYOUT_FILE = DoxygenLayout_stm32f1.xml LAYOUT_FILE = DoxygenLayout_stm32f1.xml

16
doc/stm32f2/Doxyfile
View File

@ -15,20 +15,8 @@
WARN_LOGFILE = doxygen_stm32f2.log WARN_LOGFILE = doxygen_stm32f2.log
INPUT = ../../include/libopencm3/license.dox \ INPUT = ../../include/libopencm3/license.dox
../../include/libopencm3/stm32/f2 \ @INCLUDE = doxy.sourcelist
../../include/libopencm3/stm32/common
INPUT += ../../lib/stm32/f2 \
../../lib/stm32/common
EXCLUDE =
EXCLUDE_PATTERNS = *_common_f13.h *_common_f13.c \
*_common_*f013.h *_common_*f013.c \
*_common_*f01.h *_common_*f01.c \
*_common_*f03.h *_common_*f03.c \
*crs_common_all.[ch]
LAYOUT_FILE = DoxygenLayout_stm32f2.xml LAYOUT_FILE = DoxygenLayout_stm32f2.xml

18
doc/stm32f3/Doxyfile
View File

@ -12,22 +12,8 @@
WARN_LOGFILE = doxygen_stm32f3.log WARN_LOGFILE = doxygen_stm32f3.log
INPUT = ../../include/libopencm3/license.dox \ INPUT = ../../include/libopencm3/license.dox
../../include/libopencm3/stm32/f3 \ @INCLUDE = doxy.sourcelist
../../include/libopencm3/stm32/common
INPUT += ../../lib/stm32/f3 \
../../lib/stm32/common
EXCLUDE = ../../include/libopencm3/stm32/f3/usb.h \
../../include/libopencm3/stm32/f3/usb_desc.h
EXCLUDE_PATTERNS = *_common_*f*24.h *_common_*f*24.c \
*_common_*f01.h *_common_*f01.c \
*_common_bcd.h *_common_bcd.c \
*crs_common_all.[ch]
EXCLUDE_PATTERNS += *adc_common_v1* *adc_common_v2_single*
EXCLUDE_PATTERNS += *pwr_common_l01.*
LAYOUT_FILE = DoxygenLayout_stm32f3.xml LAYOUT_FILE = DoxygenLayout_stm32f3.xml

16
doc/stm32f4/Doxyfile
View File

@ -15,20 +15,8 @@
WARN_LOGFILE = doxygen_stm32f4.log WARN_LOGFILE = doxygen_stm32f4.log
INPUT = ../../include/libopencm3/license.dox \ INPUT = ../../include/libopencm3/license.dox
../../include/libopencm3/stm32/f4 \ @INCLUDE = doxy.sourcelist
../../include/libopencm3/stm32/common
INPUT += ../../lib/stm32/f4 \
../../lib/stm32/common
EXCLUDE =
EXCLUDE_PATTERNS = *_common_f*3.h *_common_f*3.c \
*_common_*f013.h *_common_*f013.c \
*_common_*f01.h *_common_*f01.c \ \
*_common_*f03.h *_common_*f03.c \
*crs_common_all.[ch]
LAYOUT_FILE = DoxygenLayout_stm32f4.xml LAYOUT_FILE = DoxygenLayout_stm32f4.xml

16
doc/stm32f7/Doxyfile
View File

@ -15,20 +15,8 @@
WARN_LOGFILE = doxygen_stm32f7.log WARN_LOGFILE = doxygen_stm32f7.log
INPUT = ../../include/libopencm3/license.dox \ INPUT = ../../include/libopencm3/license.dox
../../include/libopencm3/stm32/f7 \ @INCLUDE = doxy.sourcelist
../../include/libopencm3/stm32/common
INPUT += ../../lib/stm32/f7 \
../../lib/stm32/common
EXCLUDE =
EXCLUDE_PATTERNS = *_common_f*3.h *_common_f*3.c \
*_common_*f013.h *_common_*f013.c \
*_common_*f01.h *_common_*f01.c \ \
*_common_*f03.h *_common_*f03.c
EXCLUDE_PATTERNS += pwr_common_v1.* pwr_common_v2.*
LAYOUT_FILE = DoxygenLayout_stm32f7.xml LAYOUT_FILE = DoxygenLayout_stm32f7.xml

20
doc/stm32l0/Doxyfile
View File

@ -15,24 +15,8 @@
WARN_LOGFILE = doxygen_stm32l0.log WARN_LOGFILE = doxygen_stm32l0.log
INPUT = ../../include/libopencm3/license.dox INPUT = ../../include/libopencm3/license.dox
INPUT +=../../include/libopencm3/stm32/l0 @INCLUDE = doxy.sourcelist
INPUT +=../../include/libopencm3/stm32/common
INPUT +=../../lib/stm32/l0
INPUT +=../../lib/stm32/common
EXCLUDE = ../../include/libopencm3/stm32/common/gpio_common_f24.h
EXCLUDE +=../../include/libopencm3/stm32/common/timer_common_f24.h \
EXCLUDE +=../../include/libopencm3/stm32/common/crypto_common_f24.h \
EXCLUDE +=../../include/libopencm3/stm32/common/hash_common_f24.h
EXCLUDE =../../lib/stm32/common/gpio_common_f24.c
EXCLUDE =../../lib/stm32/common/timer_common_f24.c
EXCLUDE =../../lib/stm32/common/crypto_common_f24.c
EXCLUDE =../../lib/stm32/common/hash_common_f24.c
EXCLUDE_PATTERNS =
LAYOUT_FILE = DoxygenLayout_stm32l0.xml LAYOUT_FILE = DoxygenLayout_stm32l0.xml

25
doc/stm32l1/Doxyfile
View File

@ -15,29 +15,8 @@
WARN_LOGFILE = doxygen_stm32l1.log WARN_LOGFILE = doxygen_stm32l1.log
INPUT = ../../include/libopencm3/license.dox \ INPUT = ../../include/libopencm3/license.dox
../../include/libopencm3/stm32/l1 \ @INCLUDE = doxy.sourcelist
../../include/libopencm3/stm32/common
INPUT += ../../lib/stm32/l1 \
../../lib/stm32/common
EXCLUDE = ../../include/libopencm3/stm32/common/gpio_common_f24.h \
../../include/libopencm3/stm32/common/gpio_common_f234.h \
../../include/libopencm3/stm32/common/timer_common_f24.h \
../../include/libopencm3/stm32/common/crypto_common_f24.h \
../../include/libopencm3/stm32/common/hash_common_f24.h \
../../include/libopencm3/stm32/common/crs_common_all.h
EXCLUDE += ../../lib/stm32/common/gpio_common_f24.c \
../../lib/stm32/common/timer_common_f24.c \
../../lib/stm32/common/crypto_common_f24.c \
../../lib/stm32/common/hash_common_f24.c \
../../lib/stm32/common/crs_common_all.c
EXCLUDE_PATTERNS = *common/flash_common_f*.*
EXCLUDE_PATTERNS += *common/adc_common_v2*
EXCLUDE_PATTERNS += *common/spi_common_f03.*
LAYOUT_FILE = DoxygenLayout_stm32l1.xml LAYOUT_FILE = DoxygenLayout_stm32l1.xml

8
doc/vf6xx/Doxyfile
View File

@ -15,12 +15,8 @@
WARN_LOGFILE = doxygen_vf6xx.log WARN_LOGFILE = doxygen_vf6xx.log
INPUT = ../../include/libopencm3/license.dox \ INPUT = ../../include/libopencm3/license.dox
../../include/libopencm3/vf6xx @INCLUDE = doxy.sourcelist
INPUT += ../../lib/vf6xx
EXCLUDE =
LAYOUT_FILE = DoxygenLayout_vf6xx.xml LAYOUT_FILE = DoxygenLayout_vf6xx.xml

21
scripts/gendoxylist Executable file
View File

@ -0,0 +1,21 @@
#!/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.
DDIR=$1
ODIR=$2
ONAME=doxy.sourcelist
PATH_DELTA=$(realpath --relative-to=${ODIR} ${DDIR})
printf "# This file is autogenerated by scripts/gendoxylist\n" > ${ODIR}/${ONAME}
printf "# Documentation only header, not caught by .d file tracking" >> ${ODIR}/${ONAME}
FN=$(find ../include/libopencm3/ -name doc-$(basename ${ODIR}).h)
printf "INPUT += ../%s\n" "$FN" > ${ODIR}/${ONAME}
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}