Bug 101444 - GObject xref links are broken in documentation
Summary: GObject xref links are broken in documentation
Status: NEW
Alias: None
Product: udisks
Classification: Unclassified
Component: general (show other bugs)
Version: unspecified
Hardware: Other All
: medium normal
Assignee: Martin Pitt
QA Contact:
URL:
Whiteboard:
Keywords:
Depends on:
Blocks:
 
Reported: 2017-06-15 11:07 UTC by Arnaud R (elboulangero)
Modified: 2017-07-19 11:33 UTC (History)
0 users

See Also:
i915 platform:
i915 features:


Attachments

Note You need to log in before you can comment on or make changes to this bug.
Description Arnaud R (elboulangero) 2017-06-15 11:07:32 UTC
Hey!

I noticed that most (if all) the links to GLib/GObject are broken in the online documentation. Example:

    http://storaged.org/doc/udisks2-api/latest/UDisksObject.html#UDisksObject.object-hierarchy

They're also broken in the documentation installed on my machine (Debian Stretch), accessible through 'devhelp'.

    /usr/share/gtk-doc/html/udisks2/UDisksObject.html

I took a bit of time to look into this, and it seems that 'gtkdoc-fixxref' needs explicit options to handle links toward external symbols.

gtkdoc-fixxref is the tool that fixes the cross-references in the documentation [1]. By default, it scans for indices in the install directory [2]. Which might defaults to '/usr/local/share' [3], where there's nothing to be found. So it's a bit of a broken behavior to start with.

Anyway, I'm not an expert in gtk-doc, but I had a look into GTK+ and GStreamer to see how they handle that. They do it the same way, by explicitly telling gtkdoc-fixxref where to look at.

I added equivalent commits for udisks, you can have a look on my branch.

clone: https://arnaud-preevio@gitlab.com/arnaud-preevio/udisks.git
branch: art/udisks-2.6.5/fix-links

I can't be 100% sure it fixes the issue, I still need to try to build a Debian package and compare the result.

As for the website, I don't know if there's more magic needed to make these links work. I didn't talk about 'gtkdoc-rebase', and I won't tell anything, apart that this guy is involved in the installation process.

Cheers,

----

[1] https://developer.gnome.org/gtk-doc-manual/stable/howdoesgtkdocwork.html.en
[2] gtkdoc-fixxref --help
[3] V=1 make
Comment 1 Arnaud R (elboulangero) 2017-06-15 15:51:37 UTC
Hmmm, talking about the Debian package, it might as well be a bug in the Debian package it self.

I can see that both gtk and gstreamer have a 'Build-Depends-Indep' field in their control file, indicating 'libglib2.0-doc' as a dependency. The udisks package has no such thing, so it's possible that it's build in an environment where the GLib documentation is not installed, and therefore the cross-reference links are not resolved.

It would be interesting to know whether the udisks documentation installed on Fedora has broken links to GLib symbols.
Comment 2 Arnaud R (elboulangero) 2017-07-19 11:33:42 UTC
That's fixed on the Debian package, see https://bugs.debian.org/cgi-bin/bugreport.cgi?bug=865956. That was probably a different bug though.


Use of freedesktop.org services, including Bugzilla, is subject to our Code of Conduct. How we collect and use information is described in our Privacy Policy.