A normal git clone doesn't catch these, as it _knows_ that the files are
in the git repo and should be tracked. However, downloading a tarball,
and adding it to a new git repo shows up the problem as important files
are simply not added, and would be dropped by git clean.
Reported-by: https://github.com/libopencm3/libopencm3/issues/1153
Generate doc root doxygenlayout file, as well as devices stuff, based on main
Makefile $(TARGETS) and template files. Avoids painfull sync/merge of 20 files+
when adding a new device.
bonus : allow to build only one device doc easily (make TARGETS=stm32f0 doc)
regression: we currently loose device "fancy" naming as device name is
guessed (toUpper()..) from folder name.
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.
New doc directory with config files and generated html, LaTeX/pdf.
Makefile provided for autogeneration and explanatory README.
The project structure is hostile to doxygen, which can't cope with functions
of the same name. Doxygen is run for each family separately, and separately
for LaTeX generation. Customized layout files sort of "integrate" HTML, and
separate pdfs are generated for each family. Not ideal but seems the best
solution until doxygen changes, if at all.
Karl Palsson