missing referenced SGML file when building documentation

kupferlauncher / keybinder

``keybinder`` is a library for registering global key bindings, for gtk-based applications in X11. With gir bindings.

MIT License

111 stars 17 forks source link

missing referenced SGML file when building documentation #16

Open andreasbaumann opened 5 years ago

andreasbaumann commented 5 years ago

version 0.3.2

./configure --prefix=/usr --enable-gtk-doc make

results in:

warning: failed to load external entity "../xml/tree_index.sgml"
../keybinder-docs.sgml:26: element include: XInclude error : could not load ../xml/tree_index.sgml, and no fallback was found
make[1]: *** [Makefile:730: html-build.stamp] Error 6
make[1]: Leaving directory '/build/libkeybinder3/src/keybinder-3.0-0.3.2/docs'

Where are those SGML file supposed to come from?

ulidtko commented 5 years ago

@andreasbaumann try running make V=1. The docs do build on my system (Ubuntu 18.04.3) from this repo master, having installed the gtk-doc-tools package.

From what I briefly tested, the whole docs/xml directory is created by a call to gtkdoc-mkdb. That call is made from toplevel gtk-doc.make included from docs/Makefile.am here: https://github.com/kupferlauncher/keybinder/blob/13b4dbd58497311652e3f703aed55e9659adfb4c/docs/Makefile.am#L84-L85

That gtk-doc.make isn't in the repo; as the comment suggests, it's put there somewhere during ./autogen.sh (hell I despise GNU Autotools).

Hope that helps.

andreasbaumann commented 5 years ago

So,

make -j <n>

with n>1 might be a problem here.. thanks :-)

andreasbaumann commented 5 years ago

Aha. Found it. Obviously in newer versions of gtkdoc it builds a xml/object_index.sgml and no longer a xml/tree_index.sgml (as referenced in keybinder-docs.sgml).

So the following snippet in keybinder-docs.sgml should contain:

Object Hierarchy



Now the problem is: how can you make documentation build with different versions
of gtkdoc?

andreasbaumann commented 5 years ago

I should say I'm using gtk-doc 1.31 on Archlinux.

ulidtko commented 5 years ago

Now the problem is: how can you make documentation build with different versions of gtkdoc?

Oh geez. @andreasbaumann can you please poke the gnome people (e.g. on IRC) on what we're supposed to do in this situation?

@GNOME thanks for breaking app compat again! You're the best!..

andreasbaumann commented 5 years ago

Poked :-)

~~https://gitlab.gnome.org/GNOME/gtk/issues/2133~~

https://gitlab.gnome.org/GNOME/gtk-doc/issues/103

andreasbaumann commented 5 years ago

Have a look at their feedback in https://gitlab.gnome.org/GNOME/gtk-doc/issues/103 :

"In your case the fix is simple - in https://github.com/kupferlauncher/keybinder/blob/master/docs/keybinder-docs.sgml#L24 - just don't include files you don't need anyway. From a quick look at your sources your library is not providing gobjects - its a plain c library."