[Development] Assistant WebKit/WebEngine support

[Kirill Burtsev]

Hi,

so it seems that it's really about look and feel in the end :)
So about that:
* as a developer i don't expect methods for QObject  in a web doc to be in a table.
Why return type should be separated from anything else? It's a proper c++ signature.
And to my taste methods list looks better in assistant/creator than on a current web
doc page https://doc.qt.io/qt-5/qobject.html. It's enough to just aligh method names
and highlight it. Why should it be more then that? Does this example really justify
adding html/css webengine?
* Tables look good at least in Model/View Programming page. How is it not
possible to display them properly?
* \code, \endcode works fine in https://doc.qt.io/qt-5/qwebengineurlschemehandler.html
Assistant and web have different highlighting, but i find assistant version better,
because it doesn't annoy with colors and only highlights important Qt classes and
dims c++ keywords. And i would definitely prefer my local creator/vim color scheme
than the one on web doc. But it's a personal preference.

And about 'what developers expect to get when they look at the documentation.' 
I would say it's answer. And the question will rarely be 'does it look the same in
assistant and doc.qt.io?' or 'How cool tables are rendered?'. This move looks more
like it would increase entropy rather than help fighting it. Implementing fuzzy
context aware searches for help with as many sources as possible event outside
of Qt programs would definitely help. Restricting users to the single ide and its
environment is a strange desire.

Regards,
Kirill

________________________________________
From: Development <development-bounces at qt-project.org> on behalf of Palaraja, Kavindra <KPalaraja at luxoft.com>
Sent: Tuesday, June 25, 2019 14:28
To: development at qt-project.org
Subject: Re: [Development] Assistant WebKit/WebEngine support

…

I don't think that a lot of developers really care about how wonderful help module looks like as long as it answers development related questions clearly and precisely. Nowadays help/doc search activities is much more than just open offline page with descriptions of classes and methods with examples. We search through QA web sites and dev forums, tutorials and videos, source repositories, social discussion platform. Why not to delegate all those activities to proper browser environment of choice with all its extensions and custom setups? And just improve query part of qtc help (index, content seaches) to speed up simple Qt and c++ related queries and fall back to proper web search engines outside of ide for anything more complex. Embedding browser into ide seems to me like a huge misdirection.


Hi Kirill,

I can’t speak for the size of WebEngine or the complexity of this solution, but I can speak for the look & feel of the documentation.

The current situation with Qt Creator’s documentation is not about how wonderful the content would look like. It’s about the basics of what developers expect to get when they look at the documentation. It’s to match what we have on https://doc.qt.io in the first place. I’m talking about _parity_. I’m not asking for some crazy animation – just a 1:1 with the official Qt documentation that’s published online.


  *   We can’t display a real code blocks in Creator – you don’t get that black box with syntax highlighted code snippets in Creator. When you document this, you use \code, \endcode, or \badcode in qdoc. None of this is actually being displayed as expected in Creator.

If source code was not behaving as expected when compiled, you’d consider it a bug right? So why is this different because it’s documentation? Because it’s less important?

  *   We can’t display a proper table with the borders in Creator – try it out, search for QObject, look at the API reference, there’s actually no table there. Just some indentation with white background. Now compare it to this: https://doc.qt.io/qt-5/qobject.html

You say:

“Nowadays help/doc search activities is much more than just open offline page with descriptions of classes and methods with examples.”

Exactly. I’d like to have more than this – but we don’t even have basic HTML. Remember, a table doesn’t render at all. It’s not possible with regular Creator docs. It’s possible to have better documentation, but we need something more than just QTextBrowser.


Kavindra.


________________________________

This e-mail and any attachment(s) are intended only for the recipient(s) named above and others who have been specifically authorized to receive them. They may contain confidential information. If you are not the intended recipient, please do not read this email or its attachment(s). Furthermore, you are hereby notified that any dissemination, distribution or copying of this e-mail and any attachment(s) is strictly prohibited. If you have received this e-mail in error, please immediately notify the sender by replying to this e-mail and then delete this e-mail and any attachment(s) or copies thereof from your system. Thank you.
-------------- next part --------------
A non-text attachment was scrubbed...
Name: modelview.doc.png
Type: image/png
Size: 226648 bytes
Desc: modelview.doc.png
URL: <http://lists.qt-project.org/pipermail/development/attachments/20190626/aee45ad1/attachment.png>