GNOME Bugzilla – Bug 761284
Have the latest stable/unstable GNOME API references
Last modified: 2017-06-29 11:48:12 UTC
I think it was discussed several years ago at a developer experience hackfest. It would be nice to have access in Devhelp to the latest stable and unstable API references of the GNOME and GTK+ libraries, in an easy way. Probably by downloading the tarballs and extract the docs in there. But Devhelp needs to know where to download the tarballs.
It was at the DeveloperExperience2014: https://wiki.gnome.org/Hackfests/DeveloperExperience2014 https://sigquit.wordpress.com/2014/05/01/profiles-in-devhelp/
developer.gnome.org could provide required info: https://developer.gnome.org/devhelp.bundles would give a list of available bundles: <devhelp-bundles> <devhelp-bundle>/devhelp-bundles/gnome-stable.bundle</devhelp-bundle> <devhelp-bundle>/devhelp-bundles/gnome-unstable.bundle</devhelp-bundle> </devhelp-bundles> And then those URIs would have pointer to relevant tarballs, ex: https://developer.gnome.org/bundles/gnome-stable.bundle → <devhelp-bundle> <title>GNOME 3.18</title> <books> <book href="/gtk3/gtk3-html-3.18.7.tar.gz"/> <book href="/glib/glib-html-2.46.2.tar.gz"/> </books> </devhelp-bundle> Then devhelp would have to download those and have some way to switch between bundles. (a default bundle would be "distribution-provided documents")
As a first iteration, let's just download the latest *stable* docs from gnome.org. There needs to be a fallback: if the latest stable doc is not downloaded, take the one from the distro. With a menu item to check if new versions are available, and download them. Maybe this can be done automatically at Devhelp startup, and show an infobar or in-app notification with a button to download the new versions. As a second iteration, a profile system can be added as is done in the aleksander/profiles branch, to choose between stable and unstable (or "development" or whatever word is nicer). Latest stable and latest unstable are the only two profiles that make sense to me. Of course for each major version, e.g. the latest GTK+ 2 and the latest GTK+ 3.
I have now manually put those files in place: https://developer.gnome.org/devhelp-bundles/index.bundles https://developer.gnome.org/devhelp-bundles/gnome-stable.bundle
And as just discussed at the new hackfest, to know if new versions are available, the manifest file on gnome.org should contain explicitly the library names and versions, in separate tags or attributes. Devhelp would have a copy of the manifest locally and can compare the two versions, and even show update information like "GTK+ 3.18.6 -> 3.18.7". But this doesn't work for the first Devhelp startup, since the manifest would not yet be downloaded. And maybe the distro has already the latest version. So maybe the manifest should also be included in the Devhelp sources.
I added title and version attributes. Let's just download the file on first startup and consider it will always be newer than the local copies.
In Builder, we will be getting xdg-app integration landing soon. That means that we'll have access to the GNOME SDK (and ideally the docs shipped as part of the SDK, or optionally another runtime which is based on the SDK+devhelp books). We can access the xdg-app runtime/sdk via a path prefix, so loading from a specific directory would do us just fine when loading the DhBookManager. We just need a hook in DhBookManager to set the search path.
The TODO file contained an item on "online download", see commit 8a17ba502a5d52a64a03538d10d7f6b7ddfcabdc.
*** Bug 760313 has been marked as a duplicate of this bug. ***