Created attachment 354858 [details] [review]
BookManager: allow custom search paths for documentation

There are situations where an application using libdevhelp would
want to use a custom search path for the documentation location.
One such example is Builder where it needs to display
documentation that is coming from a Flatpak SDK or the built
application dependencies. Another possible example would be an
application that is displaying bundled or downloaded
documentation from an online SDK.

For the Builder-case, this allows using a search path including
the Flatpak/OStree deploy directory for "/app" and "/usr". In
doing so, the existing GFileMonitor code can continue to work
and update the book list as the user's project dependencies are
built.

Signed-off-by: Christian Hergert <chergert@redhat.com>

Review of attachment 354858 [details] [review]:

Now that DhBookManager is a singleton, I think we can undeprecate populate(), and add a function to configure the search path.
So basically:
1. get_singleton()
2. optionally call set_search_path() to change the default paths
3. populate() (called only once, in the Devhelp app it would be called during GtkApplication startup for example).

If a feature uses the DhBookManger before it is populated, the feature anyway receives updates with the book-created signal.

(btw the Signed-off-by in the commit message is not required in gnome).

Do you need to create several DhBookManager instances? Because with the singleton it won't work. The singleton should contain all DhBooks found on the system. Maybe what you need is a DhBookSelection object or something like that. With DhBookSelection it would be possible to filter the programming language, filter specific books, maybe later filter stable/unstable versions, things like that.

(In reply to Sébastien Wilmet from comment #3)
> Do you need to create several DhBookManager instances? Because with the
> singleton it won't work. The singleton should contain all DhBooks found on
> the system. Maybe what you need is a DhBookSelection object or something
> like that. With DhBookSelection it would be possible to filter the
> programming language, filter specific books, maybe later filter
> stable/unstable versions, things like that.

I would find it much more convenient from a code standpoint in Builder to have a DhBookManager per-project. That way my only configuration point is the search paths rather than having to introspect into the project and determine what to show and hide.

It can also change for us at runtime if the user changes the runtime their application is targeting. With a 1:1 mapping of DhBookManager to a project, we can just monitor for changes to the build configuration and reload the book manager.

That also means that if you select a runtime of host, jhbuild, or a flatpak runtime, you get the appropriate books.

It would have a bit more memory overhead when duplicate books are loaded, but not many people have multiple workbenches open in Builder today so that is fine.

(In reply to Christian Hergert from comment #4)
> I would find it much more convenient from a code standpoint in Builder to
> have a DhBookManager per-project. That way my only configuration point is
> the search paths rather than having to introspect into the project and
> determine what to show and hide.

DhBookSelection could also filter by path.

> It can also change for us at runtime if the user changes the runtime their
> application is targeting. With a 1:1 mapping of DhBookManager to a project,
> we can just monitor for changes to the build configuration and reload the
> book manager.
> 
> That also means that if you select a runtime of host, jhbuild, or a flatpak
> runtime, you get the appropriate books.

I do not share the same vision for Devhelp. At some point I would like to implement bug #761284 and bug #784331 (and this would just be a beginning). As a developer, I prefer to read the latest docs (for each major version, e.g. the latest GTK+ 3 and the latest GTK+ 4). Because it's important to know the new deprecations, it would be stupid to write new code that uses an API that is already deprecated in a later minor version. And also the latest doc is potentially better, because the doc is continuously improved on the master branch, to add some missing details, fix GI annotations, write more complete class descriptions, etc etc.

So I do not like your idea about showing the doc of a specific flatpak runtime.

And while it can make sense on paper to show only the libraries that an application currently depends on, I think it can get in the way:
- When developing an application, sometimes we need a new dependency, so it would be convenient to search in Devhelp a suitable library/API.
- When developing an API and we don't know exactly how to name things, it's convenient to search in Devhelp for prior art.

That all seems reasonable, given the ability to turn off unstable books that are downloaded/etc.

Do you have any time-frame on when you can get around to that (and associated access to the online books)? I can carry patches in our Flatpak builds in the mean time, but if it's going to be done in time for 3.26 I don't need to waste any time on that.

It will definitely not be done for 3.26.

I've done a brain dump about re-architecting DhBookManager and DhBook:
https://git.gnome.org/browse/devhelp/commit/?id=6493c0c554279fe885b2072ae1872a1ad2788217

With DhBookSelection and DhBookListDirectory it will be much more flexible.

Thanks for the write-up! Seems like a good plan of action to me.

For Builder 3.26, we did this nasty hack where we symlink the flatpak'd org.gnome.Sdk.Docs gtk-doc data into $XDG_DATA_DIR/gtk-doc so libdevhelp picks it up. It's a terrible workaround, but at least we have docs until something like this can land.

Done, with DhProfile and DhBookList.