Build: Add a makefile target for Doxygen documentation #12029

You can now build the doxygen documentation with make docs and clean it with make clean-docs.

Fixes: #11949

Tested 0f36dba. make docs and make clean-docs work as intended. @theuni Any thoughts here?

Looks after a good start. utACK 0f36dba0ef33344c9e73a409cad24b5b90d70f0f

Not sure if we should check and inform if doxygen is not present.

Thanks!

This needs to be documented in one of the READMEs, so that people know the targets exist.

Not sure if we should check and inform if doxygen is not present.

Possible improvement would be to check if doxygen is present in configure.ac, otherwise disable this functionality. Also to not hardcode doxygen command, but use $(DOXYGEN) or such so that it can be overridden. But yes seems a good start as-is.

Thank you for your feedback.

Possible improvement would be to check if doxygen is present in configure.ac, otherwise disable this functionality.

At the moment this target it's not executed on a simple make and if you don't have the doxygen command available you get a sensible error message and exit code:

doxygen doc/Doxyfile
make: doxygen: Command not found
make: *** [Makefile:1307: docs] Error 127

Do you want me to add this target to the default build pipeline, but only if $(DOXYGEN) exist? If not, i'm not sure what you mean when you say to disable it when the command doesn't exist, since this patch doesn't do anything until you invoke make docs or make clean-docs deliberately, in which case you already get a sensible result.

No problem with the other changes, i'll make them as soon as i have some free time.

Concept ACK. Agreed with @laanwj's comments.

doxygen may not be found in the user's path, it may instead be passed like: ./configure DOXYGEN=/my/path/to/doxygen.

Having it configured as a tool in configure.ac ensures that that works properly. It also means that we can skip it if it's ever added to the main build, but doxygen isn't installed.

Please use real makefile targets so that the dependencies are obvious. And lastly, please hook it up to clean-local so that 'make clean' removes them as well. Something like:

doc/doxygen/.stamp: doc/Doxyfile FORCE
	$(MKDIR_P) $(@D)
	$(DOXYGEN) $^
	$(AM_V_at) touch $@
docs: doc/Doxygen/.stamp

clean-docs:
	rm -rf doc/doxygen

...

clean-local: clean-docs

I made a new commit (rebased on current master) that implement the requested changes:

• configure support
• disable in case doxygen is missing
• note in the documentation

Let me know of you want me to add something else, thanks.

Looks good to me! Can you take another look @theuni?

Thanks for addressing everything. utACK a777244e48227db6d3fd06cd2500cc007dacfb10.

utACK a777244

ACK a777244. Only checked that make docs prints an error, when doxygen is not present.