Bug 312363 – gnome2 eclass: gtk-doc documentation installed outside of /usr/share/doc/${PF}

• Status: RESOLVED WONTFIX
• Product: Gentoo Linux

[Description Samuli Suominen (RETIRED) 2010-03-31 11:35:28 UTC]

Problem:

--- /usr/share/gtk-doc/
--- /usr/share/gtk-doc/html/
--- /usr/share/gtk-doc/html/ORBit2/
>>> /usr/share/gtk-doc/html/ORBit2/ORBit2-orbit2-allocators.html
>>> /usr/share/gtk-doc/html/ORBit2/left.png
>>> /usr/share/gtk-doc/html/ORBit2/ORBit2.devhelp
>>> /usr/share/gtk-doc/html/ORBit2/right.png
>>> /usr/share/gtk-doc/html/ORBit2/up.png
>>> /usr/share/gtk-doc/html/ORBit2/ORBit2.devhelp2
>>> /usr/share/gtk-doc/html/ORBit2/index.html
>>> /usr/share/gtk-doc/html/ORBit2/style.css
>>> /usr/share/gtk-doc/html/ORBit2/ORBit2-orbit2-small.html
>>> /usr/share/gtk-doc/html/ORBit2/home.png
>>> /usr/share/gtk-doc/html/ORBit2/index.sgml
>>> /usr/share/gtk-doc/html/ORBit2/general.html

Solution:

--with-html-dir=PATH    path to installed docs

[Comment 1 Gilles Dartiguelongue (RETIRED) 2010-03-31 11:56:26 UTC]

 ls /usr/share/gtk-doc
html

That's how gtk-doc is stored for all packages using gtk-doc.

[Comment 2 Gilles Dartiguelongue (RETIRED) 2010-03-31 11:56:36 UTC]

*** Bug 312365 has been marked as a duplicate of this bug. ***

[Comment 3 Samuli Suominen (RETIRED) 2010-03-31 11:58:57 UTC]

reopening

yes, all those packages in there are broken

[Comment 4 Gilles Dartiguelongue (RETIRED) 2010-03-31 12:33:57 UTC]

that's the way gtk-doc works, what do you expect...

[Comment 5 Samuli Suominen (RETIRED) 2010-03-31 12:37:10 UTC]

(In reply to comment #4)
> that's the way gtk-doc works, what do you expect...
> 

for maintainers to pass correct --with-html-dir= flag in ebuild(s) to respect gentoo standards.

[Comment 6 Gilles Dartiguelongue (RETIRED) 2010-03-31 15:40:25 UTC]

and breaking how to software works ??? devhelp relies on gtk-doc documentation to be installed in this directory.

[Comment 7 Gilles Dartiguelongue (RETIRED) 2010-03-31 15:42:26 UTC]

err, I forgot to mention the gtk-doc tools themselves which need to know where to find other gtk-doc to do the cross-linking for example.

[Comment 8 Samuli Suominen (RETIRED) 2010-03-31 15:59:23 UTC]

Then symlink like Debian does e.g. 

http://packages.debian.org/sid/amd64/liborbit2-dev/filelist

Documentation would be in correct place and devhelp continues to work. Same for cross references (which wouldn't be problem at all if you'd just install the pregenerated docs instead of rebuilding them)

[Comment 9 Gilles Dartiguelongue (RETIRED) 2010-03-31 16:01:00 UTC]

then this is a job for the eclass, I will close the other bug as a duplicate of this one if you agree.

[Comment 10 Samuli Suominen (RETIRED) 2010-03-31 16:04:36 UTC]

(In reply to comment #9)
> then this is a job for the eclass, I will close the other bug as a duplicate of
> this one if you agree.
> 

sounds good

[Comment 11 Gilles Dartiguelongue (RETIRED) 2010-03-31 23:57:32 UTC]

Created attachment 226043 [details, diff]
gtk-doc QA fix proposal

How about this patch ? It seems to do the job fine here.

[Comment 12 Gilles Dartiguelongue (RETIRED) 2010-03-31 23:58:56 UTC]

*** Bug 312365 has been marked as a duplicate of this bug. ***

[Comment 13 Mart Raudsepp 2010-04-01 04:13:04 UTC]

We should discuss this in a meeting.

To me it is a very hard sell to do things different from upstream without consulting upstream.

[Comment 14 Gilles Dartiguelongue (RETIRED) 2010-11-23 09:43:55 UTC]

*** Bug 295757 has been marked as a duplicate of this bug. ***

[Comment 15 Gilles Dartiguelongue (RETIRED) 2011-02-25 09:37:26 UTC]

For the record, if QA doesn't state whether they like this solution or not, I'm going to go over all packages installing gtk-doc in /usr/share/doc/${PF}/html thus _breaking_ devhelp and change them back to their defaults.

It is extremely annoying that when you install a package that has docs, you can't find it in devhelp where it would appear just fine were the defaults not altered to OCD locations.

[Comment 16 Gilles Dartiguelongue (RETIRED) 2011-03-28 11:48:46 UTC]

FTR, Betelgeuse pointed me to DOC_SYMLINK_DIR variable, but since it looks like a user controlled variable, I don't want to mess with it. So unless there is any objection, I'll commit an updated/fixed patch like the one attached to the eclass by the end of the week all will walk through packages installing gtk-doc by hand and not making symlinks.

[Comment 17 Alexandre Rostovtsev (RETIRED) 2011-12-17 19:08:16 UTC]

With all due respect, the Gentoo way of installing API documentation in a location that changes on every revision and minor version bump is 100% INSANE, a relic of ancient times from before the invention of slots, and this ancient insanity should not be forced on projects that have reasonable doc handling provided by upstream.

Do we append $PF to executable names, or install then in /usr/bin/$PF? What about man pages, does installing them in /usr/share/man/$PF sound like a good idea? No, of course not. Then why would anyone think that versioning the API documentation path via $PF is a reasonable thing to do?

This is not an error in gnome2.eclass or gnome ebuilds. This is an error in Gentoo standards that needs to be solved via glep.

[Comment 18 Gilles Dartiguelongue (RETIRED) 2012-12-27 22:17:02 UTC]

Gnome herd decided against installing gtk-doc outside of it's intended location.
Some of the arguments got written to gentoo wiki as an effort to make Gnome herd policies clear and document before moving eventually to regular gentoo docs.

See https://wiki.gentoo.org/wiki/Gnome_Team_Policies