GNOME Bugzilla – Bug 744864
wip concept: move away from gtkdocize
Last modified: 2018-05-22 13:09:54 UTC
Here are some changes that should allow modules to move away from using gtkdocize. Instead, you just need to add this in your docs/ Makefile.am: if HAVE_GTK_DOC include $(GTK_DOC_MAKEFILE) dist-hook: # do not remove! endif in place of the normal hard-coded include. Most of the disruption here is caused by the fact that the make fragment is no longer copied into the tree and is therefore no longer available at autoreconf time. That means that we have to port the Makefile from being an automake fragment to working in pure make. The 'dist-hook:' hack is required because automake will fail to emit the hook at all if it doesn't see someone using it (and it won't see it in the included makefile, as mentioned above). It would be better to move away from using the dist hook entirely, but there are two complications: 1) it's not entirely clear what the role of gtkdoc-rebase is here or if it's even required anymore (it seems not to be) 2) it will be awkward to know which html files to install if those files did not exist when make was invoked (ie: if the user skips 'make' and just goes straight to 'make install')
Created attachment 297453 [details] [review] wip concept: move away from gtkdocize
What is the actual issue with gtkdocize? Regarding the make fragment - I was thinking of introducing a tool gtkdoc that will call gtkdoc-scan, gtkdoc-mkdb, ... internally. this will reduce the make rule to all-gtk-doc: $(HFILE_GLOB) $(CFILE_GLOB) $(DOC_MODULE)-decl.txt $(SCANOBJ_FILES) $(DOC_MODULE)-sections.txt $(DOC_MODULE)-overrides.txt $(expand_content_files) $(content_files) gtkdoc --module=$(DOC_MODULE) <options> The main motivation is to get rid of the makefile mess and have more control over the dependencies. Not sure how easy this would be though.
(In reply to Stefan Sauer (gstreamer, gtkdoc dev) from comment #2) > What is the actual issue with gtkdocize? Ryan is trying to get rid of autogen.sh, or at least reduce it to a simple autoreconf call. > Regarding the make fragment - I was thinking of introducing a tool gtkdoc > that will call gtkdoc-scan, gtkdoc-mkdb, ... internally. this will reduce > the make rule to > > all-gtk-doc: $(HFILE_GLOB) $(CFILE_GLOB) $(DOC_MODULE)-decl.txt > $(SCANOBJ_FILES) $(DOC_MODULE)-sections.txt $(DOC_MODULE)-overrides.txt > $(expand_content_files) $(content_files) > gtkdoc --module=$(DOC_MODULE) <options> > > The main motivation is to get rid of the makefile mess and have more control > over the dependencies. Not sure how easy this would be though. I'm all in favour of getting rid of the Makefile mess. Would this not effectively mean reimplementing a considerable amount of Make's dependency tracking system?
(In reply to Philip Withnall from comment #3) > (In reply to Stefan Sauer (gstreamer, gtkdoc dev) from comment #2) > > What is the actual issue with gtkdocize? > > Ryan is trying to get rid of autogen.sh, or at least reduce it to a simple > autoreconf call. Too bad, one can't register additional tools to run here. > > > Regarding the make fragment - I was thinking of introducing a tool gtkdoc > > that will call gtkdoc-scan, gtkdoc-mkdb, ... internally. this will reduce > > the make rule to > > > > all-gtk-doc: $(HFILE_GLOB) $(CFILE_GLOB) $(DOC_MODULE)-decl.txt > > $(SCANOBJ_FILES) $(DOC_MODULE)-sections.txt $(DOC_MODULE)-overrides.txt > > $(expand_content_files) $(content_files) > > gtkdoc --module=$(DOC_MODULE) <options> > > > > The main motivation is to get rid of the makefile mess and have more control > > over the dependencies. Not sure how easy this would be though. > > I'm all in favour of getting rid of the Makefile mess. Would this not > effectively mean reimplementing a considerable amount of Make's dependency > tracking system? Yeah, I am not sure what the right way forward is, but if you look at other doc-generators - they are just single commands to run (doxygen, javadoc, ...). In any case the main work missing here is to simplify the makefile to be a plain makefile :/ and e.g. pulling some logic into the tools could be one way.
(In reply to Stefan Sauer (gstreamer, gtkdoc dev) from comment #4) > In any case the main work missing here is to simplify the makefile to be a > plain makefile :/ and e.g. pulling some logic into the tools could be one > way. Yeah, any logic that could be pulled into the tools would simplify things.
FYI: there is also https://bugzilla.gnome.org/show_bug.cgi?id=758313
-- GitLab Migration Automatic Message -- This bug has been migrated to GNOME's GitLab instance and has been closed from further activity. You can subscribe and participate further through the new bug through this link to our GitLab instance: https://gitlab.gnome.org/GNOME/gtk-doc/issues/31.