D8211: KDevelop/Documentation : implementation of a QTextBrowser-based viewer

Fri Oct 20 09:18:39 UTC 2017

rjvbb added a comment.

  >   But what is the value of integrating documentation, apart from not having to leave the window? The integration with the code: being able to quickly get the documentation for a piece of API I'm using. But that doesn't exclude using an external application to actually view the documentation.

  Exactly (also the bits about hovering over a function - if that didn't exist I wouldn't even be bothering trying to improve the whole documentation viewer interface). The drawback of an integrated viewer in the kind of UI KDevelop puts up is that most of the time it's going to interfere with the very workflow it aims to streamline. Either you get a docked view which is probably too small while impeding too much on your code area (and thus the text flow in there) OR you get an external "floating" window which cannot easily be put exactly where you want it where it doesn't cover the main window. Not to mention when you have 2 sessions open and want to refer in session 1 to documentation displayed in session 2.
  It's not for nothing that Qt Creator, Xcode and (IIRC) MSVC don't propose an embedded view (or not by default) and use a regular window.

  There are other advantages to an external browser (controlled via the IDE) but that's indeed OT here.

  As to the manpage plugin: I never use it. I see Aaron's point, but for me it's much faster to switch to a terminal window (using keyboard shortcuts) than to mouse to the manpage toolview and find the documentation I want in there. Most of the time reading a manpage involves using `apropros` first, anyway.

  > Sections cannot be toggled, are open/closed randomly after loading (no pattern seen over the time):

  What you seem to be getting at here is using KDevelop as a documentation browser. I don't know what kind of (huge?) screen you use, but if it's not some crazyhighres affair used with 10-12pt fonts by a user with eagle sight there cannot be much space left for actual code. It seems to me that when application time is spent clicking on documentation layout gimmicks (excusez le mot), that application misses its goal when it wants to be something other than a documentation browser.

  FWIW, Qt Creator's documentation browser is nice, a pleasure to use as far as I know it. Sadly it's integrated into something that's not a snap to load - and that applies to all those fancy embedded documentation browsers. (The one in Xcode is even worse.)

  > Method titles are partially hidden, tags like virtual,visibility,abstract hard to read due to missing spacing ()

  I'm not seeing this, not to the same extent at least, and as I said, my KF5 qch documentation is generated with the latest doxygen, kapidox (currently 5.38.0) and Qt 5.8.0 . I'd have to see how this works when I strip support for the embedded CSS, which apparently I'll have to do anyway.

  Re: Qt Assistant and its rendering backend: my recollection was a bit off. In practice we're both right: it'll use QWK if available and QTB otherwise. When you're building Qt from scratch (e.g. using the exhaustive tarball) QWK won't be available (in the build tree) and you'll thus get the QTB backend. Took me a while to figure that out, a couple of Qt releases back. I'm now making sure that I build this component with QWK available (and probably force the .pro file to use it.
  Building a copy of Assistant that has QWK support isn't hard at all, and takes minutes only, so that shouldn't be an obstacle for KDevelop's target user population. We can provide documentation how to do that, too. I'm a bit surprised Qt haven't yet implemented a QWE backend, btw.

  So, for the record, I'm dropping the idea that KDevelop might make the QTB backend the only or the default backend. I'm fine with the cmake implementation as it is, where you get QTB only when QWK and QWE are either disabled or unavailable.

  > still need to clean-up and push the rest of it

  Oh joy, more refactoring work for me ahead...  And:

  > to wok as I need it

  (sic). I do presume you won't push that without proper review - I'm not the only user who can presume his doc viewing needs can be projected as is on the whole user population.

  > Reads to me like "it is good enough for me because I do not use it (and thus do not care but you are invited to collaborate)". This approach is not really "collaborative", or?

  And "I want you to add this, modify that, and in general dot the i's exactly as I tell you" is so much more collaborative? We're all volunteering our work on this, and I think it's perfectly reasonable to expect that everyone works on what s/he cares most about. It's a pity that phab doesn't allow multiple users to work on a single patch directly. But I'll test and consider all serious contributions to this patch. Including one that makes runtime selection of a backend possible. (If we're starting to think about using an env. var to select the backend we might just as well implement runtime switching, so that plugins can -or have to- provide their preferred backend.)
  BTW, @Friedrich: maybe you can integrate your idea of selectable backends with your pending changes - the CI arguments you advanced should apply to your changes too. My current patch should give you a pretty good idea about the few API additions that are required for QTB support. I can then see how I can refactor my patch to integrate with yours with minimal #ifdefs. I'd have to do that anyway.

  As to 3rd party plugins: does it shock if they don't all support all possible backends, in particular a QTB backend?

  > Purpose of this patch seems: get rid of some dependency.

  That was indeed the initial reason and is still the main reason. All the other work done after that became possible (as a fallback solution) was to make this fallback mode work better. There. 
  I remain convinced that dependencies as big as QWK and esp. QWE come with significant resource use (once you actually use them), but you're welcome to disregard that argument since I'm not providing proof.

  > People seem to have problems with using a full-featured web browser backend "just because!"

  I cannot speak for all those people, but a full-featured browser backend makes sense in a browsing application, i.e. one where browsing is the main application. Apparently that even requires integrated bluetooth support nowadays, but I digress. KDevelop will need to make choices if it wants to maintain a remain manageable for both developers and users.

  Don't forget that not all users have access to pre-built packages (you can't just grab QWE from Qt's builds and use it with a random "system" Qt build).

  I tried the QWE backend, to verify if my patch affected anything. Activating it felt like turning on the airco on an older car with too tiny an engine, and IIRC gave me systematic crashes on exit on Mac. (I ignored them because I won't be using that backend.)

  > (for no world-changing reason, and just to make a handful of developer's life more easy)

  All due respect, but that applies to just about all changes made to KDevelop. Just how many core developers are there, and what proportion of invasive changes gets put up for review with a honest attempt to obtain feedback from the entire user community?

  To conclude: the purpose of this patch is to provide a fallback backend that works reasonably well for those of us who have their reasons to want a lean-as-possible KDevelop build. Despite what my choice of words in earlier posts may have suggested (suggestions to drop the other backends have been taken back). It's not intended to push for the use of an external browser.  I'll see about mimimising the #ifdefs, and how we can get the rendered version to look like in the contextual popups (= simplified, not crippled). Documentation doesn't necessarily have to look good (= fancy), but it sure has to be readable.

  Is it still an obligation to have a documentation viewer beyond those contextual help popups? Those would be enough for me, once something like https://phabricator.kde.org/D4484 gets committed.

REPOSITORY
  R32 KDevelop

REVISION DETAIL
  https://phabricator.kde.org/D8211

To: rjvbb, #kdevelop
Cc: kfunk, croick, kossebau, aaronpuchert, flherne, arichardson, apol, kdevelop-devel, geetamc, Pilzschaf, akshaydeo, surgenight, arrowdodger
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://mail.kde.org/pipermail/kdevelop-devel/attachments/20171020/ff850273/attachment-0001.html>