GNOME Bugzilla – Bug 668461
Add autotools integration (i.e. m4 macros)
Last modified: 2021-06-10 20:55:35 UTC
Allow to integrate building valadoc documentation from autotools in native way.
Created attachment 213425 [details] [review] Add autotools helpers Comments welcome. To use, copy the m4 and do VALADOC_CHECK([0.3.2]) in your configure.ac, and something like this in your Makefile.am: if ENABLE_VALADOC include $(VALADOC_MAKEFILE) VALADOC_MODULES = doc doc_DOCLETS = html gtkdoc doc_OUTPUT = $(builddir)/doc doc_FLAGS = \ --driver=0.16.x \ --pkg gio-2.0 \ --target-glib 2.32 \ $(NULL) doc_PACKAGE_NAME = bump-@BUMP_API_VERSION@ doc_PACKAGE_VERSION = @BUMP_API_VERSION@ doc_SOURCES = $(libbump@BUMP_API_VERSION@_la_SOURCES) bump_gtkdoc_FLAGS = \ -X --ignore-headers \ -X bump-@BUMP_API_VERSION@-internal.h \ -X bump.h \ -X config.h \ -X -l -X libbump@BUMP_API_VERSION@.la \ $(NULL) BUILT_SOURCES += $(foreach doclet,$(bump_DOCLETS),$(bump_OUTPUT)/$(doclet)) endif
Created attachment 213531 [details] [review] Add autotools helpers Updated version which passes --driver automatically when valac is installed.
(In reply to comment #1) > Comments welcome. It would be good if this included rules to clean and distribute the generated documentation files. I guess this is only possible/reliable if Makefile.valadoc maintains an explicit list of the generated documentation files. This would also allow more explicit dependencies between the .vala files and the corresponding generated documentation files to be maintained. If rules are included to clean generated files, they should also be integrated with git.mk to make sure that the generated files aren’t listed by `git status`.
Some more feedback from playing around with this a little: • $(module)_SOURCES is a bad name for a variable, since automake reserves ‘*_SOURCES’ names. GIR seems to use $(module)_FILES instead. • Passing in --pkg manually seems a bit boring. Could we add a $(module)_PKGS variable which would do that magically? • Why doesn’t $(module)_PACKAGE_[NAME|VERSION] default to $(PACKAGE_[NAME|VERSION])? • It would be nice if the rules for installing all the generated files were included in Makefile.valadoc. • Looking into it a bit, it’s not possible for the Makefile itself to determine explicit dependencies between .vala files and the corresponding documentation files. However, it would be possible if valadoc supported a dependency-listing mode. This could be used with magic from http://mad-scientist.net/make/autodep.html to automatically track the dependencies and keep lists of the generated files so they can be explicitly cleaned (or installed). e.g. `valadoc --generate-deps --doclet=html some.vala source.vala files.vala` would produce output like: docs/html/MyClass.html docs/html/MyClass.some-member.html: src/some.vala docs/html/OtherClass.html: src/files.vala docs/html/index.html: src/some.vala src/source.vala src/files.vala Perhaps it would be more efficient if this was, instead, a “--generate-deps-file=filename” parameter passed to valadoc when it’s invoked to build the docs, so that the deps file is generated in parallel.
GNOME is going to shut down bugzilla.gnome.org in favor of gitlab.gnome.org. As part of that, we are mass-closing older open tickets in bugzilla.gnome.org which have not seen updates for a longer time (resources are unfortunately quite limited so not every ticket can get handled). If you can still reproduce the situation described in this ticket in a recent and supported software version of valadoc, then please follow https://wiki.gnome.org/GettingInTouch/BugReportingGuidelines and create a new ticket at https://gitlab.gnome.org/GNOME/valadoc/-/issues/ Thank you for your understanding and your help.