Support Quick Docs (Web Platform Docs) in HTML

[marcelgerber]

Enables Quick Docs for HTML.
Data is still from Web Platform Docs, while HTML data is in html.json and CSS data in css.json.

As there's docs for both tags and attributes, the behaviour is different based on the cursor position.

• If the cursor's on a (supported) tag like div, docs for the tag will be shown.
• If the cursor's on a (supported) attribute like tag (but not on its value!), docs for the attribute will be shown.
• If the cursor's on a unsupported attribute, docs for the tag will be shown (if supported).

Also, there's a new fullscreen-summary class applied when there's only a summary to display and nothing else (this can happen for CSS as well, but only for very few properties). But HTML docs only consist of a summary and thus, it would look odd if it was only half-screen.
Also, the summaries are mostly only consisting of one or two lines (that's what a summary is for) and in fact, that's really short. So I guess the main benefit of Quick Docs in HTML is having the "Read more" link for most users (to get things like Examples, syntax, ... that we can't access via their API). But for some users, like for those learning HTML, even such a short summary can be really helpful.

For #9566.

[le717]

Regex capture groups can be expensive. Is it possible to use a non-capturing group here (/^-(?:webkit|moz|ms|o)-/)?

[marcelgerber]

Done.

[nethip]

@ryanstewart Would you mind taking a look at what this PR is doing and tell us we want this in?

[JordanTheriault]

Missing a newline here

[humphd]

We're using this in Bramble, and we noticed that there's no support for img in html.json, despite the fact that it exists.

    "html/elements/i": {
      "SUMMARY": "<p>The <strong>i</strong> element indicates that the contained text is in an alternate voice, mood, or language from the surrounding text. ",
      "URL": "https://docs.webplatform.org/wiki/html/elements/i"
    },
    "html/elements/iframe": {
      "SUMMARY": "<p>The <strong>iframe</strong> element (&lt;iframe&gt;) introduces a new nested browsing context. ",
      "URL": "https://docs.webplatform.org/wiki/html/elements/iframe"
    },

The docs are at https://docs.webplatform.org/wiki/html/elements/img. If what I'm seeing in html.json is right, that file is pretty old: "DATETIME":"Thu, 27 Nov 2014 17:20:38 GMT.

[marcelgerber]

Oh that's weird. The Web Platform API returns an empty summary for this and only this page ("html/elements/img":{"printouts":{"Summary":[]},"fulltext":"html/elements/img","fullurl":"//docs.webplatform.org/wiki/html/elements/img"}, part of the bloody mess from https://docs.webplatform.org/w/api.php?action=ask&format=json&query=%20%5B%5BPath%3A%3A~html/elements%2F*%5D%5D%7C%3FSummary%7Cprettyprint%3Dno%7Climit%3D1000000) @webplatform

[marcelgerber]

@renoirb As you seem to be working on the Web Platform Docs, could you maybe have a look into why html/elements/img doesn't have a summary (in the API output linked above) whereas every other HTML element has one?
Thanks a lot!

[prafulVaishnav]

@marcelgerber API return ja version summary for elements too. As we are not using it, is there any way to not get it? 3 unit tests are failing. Can you please look into that.

[prafulVaishnav]

Can you create separate variable for cssLike language and html language like cssSupportedLangs = ["css", "scss", "less"] and htmlSupportedLangs = ["html"]. That way it would be easy to extend for other languages in future.

[Denisov21]

Hi,
Can you move this to Breackets Realise 1.7?

[marcelgerber]

I'm also honestly thinking about switching over to MDN docs, as they are more recent, more thorough, and more commonly used.

What do you think, @nethip @Denisov21?

[nethip]

@marcelgerber 👍 for switching to MDN.

[Denisov21]

@marcelgerber Okay for me. Good idea!

Inviato da smartphone Sony Xperia™

---- Marcel Gerber ha scritto ----

I'm also honestly thinking about switching over to MDN docs, as they are more recent, more thorough, and more commonly used.

What do you think, @nethip @Denisov21?

—
You are receiving this because you were mentioned.
Reply to this email directly or view it on GitHub

[swmitra]

@marcelgerber I don't see any pending action in this PR.
Do we need to update the html.json? Also is it web-scrapped from MDN html meta data?
If we can retain the committed documentation without immediate update, then I will merge this PR 😄

[humphd]

fwiw, we wrote an MDN based version of this a long time ago as a separate extension: https://github.com/mozilla/brackets/tree/master/src/extensions/extra/MDNDocs

[renoirb]

On a related note;

…

On Feb 17, 2017 11:24, "David Humphrey" ***@***.***> wrote: fwiw, we wrote an MDN based version of this a long time ago as a separate extension: https://github.com/mozilla/brackets/tree/master/src/ extensions/extra/MDNDocs — You are receiving this because you were mentioned. Reply to this email directly, view it on GitHub <#10036 (comment)>, or mute the thread <https://github.com/notifications/unsubscribe-auth/AASH7B_ltLPmZcw_30K4s0aOsyw3r_HVks5rdcmugaJpZM4DBh9j> .

[renoirb]

[[ Hit send too quickly ]] On a related note.

*Notice:* The WebPlatform project has been *discontinued* when the Stewards

partnership <http://www.webplatform.org/blog/2012/10/one-small-step/> agreement ended in *September 2015*. This site has been frozen, and the assets we have created will remain. Also, for compatibility data at Mozilla, you should have a look at BrowserCompat project. https://browsercompat.herokuapp.com It's a nice project to expose compat data and specs status over JSONAPI format. On Feb 17, 2017 11:24, "David Humphrey" <notifications@github.com> wrote: fwiw, we wrote an MDN based version of this a long time ago as a separate extension: https://github.com/mozilla/brackets/tree/master/src/ extensions/extra/MDNDocs — You are receiving this because you were mentioned. Reply to this email directly, view it on GitHub <#10036 (comment)>, or mute the thread <https://github.com/notifications/unsubscribe-auth/AASH7B_ltLPmZcw_30K4s0aOsyw3r_HVks5rdcmugaJpZM4DBh9j> .

[ficristo]

@humphd Nice!

Some questions, things I noticed:

• is it a drop in replacement of Webplatform docs? If so we could rename it to try to preserve the git history
• are the api you are using for scraping documented somewhere?
• should we retain our unit tests? (It seems to me you don't have any)
• IMO the app for the scraping shouldn't be part of the distribution. So we could create a new repo (maybe at brackets-userland org) or see what we can do with the build system (avoid to copy it for the dist or create a specific task or something...)

@adobe/brackets-committers any thought?

[saurabh95]

@humphd I tried running the app and I was able to generate html.json and css.json, but in css.json it gives only url and summary, and currently we have the description of values supported for a particular attribute as well, so is there a way to get info about the values of a particular css attribute?

[humphd]

cc @JordanTheriault, who worked on the code originally. @saurabh95 I think what we have now is really best viewed as a prototype, and it's not been well maintained. I suspect that we could extend it to do what's needed, perhaps one of my current students would be interested in working on it. NOTE: we don't currently ship/use it in Thimble, we still use the WebPlatformDocs with the extra html patch that @marcelgerber wrote once upon a time.

[renoirb]

On a related note. W3C system Team actually did flip the switch off from WebPlatform Docs' MediaWiki instance (what was driving the site). All of it is now only static HTML hosted on GitHub pages reading from converted to Markdown history. -- I wrote the migration This is to nail the point that WebPlatform is on its own. W3C and all sponsors won't support it any further. Unless a comunity emerges. That's outside of the scope of this ticket. We should close this issue. Renoir -- *Renoir Boulanger* https://renoirboulanger.com/ <https://renoirboulanger.com/#is> ✪ @renoirb <https://github.com/renoirb> Check my availability: <https://freebusy.io/renoirb@gmail.com> Meet me: <https://appear.in/renoirb> ~

[ficristo]

@saurabh95 it doesn't seem the tests were ported on the new code.
Maybe you can close this and open a new PR with the tests?

[saurabh95]

Yeah, will do that

[ficristo]

These changes were merged as part of #13268 and #13285.
Closing.
Thanks @marcelgerber