Update Web Platform Docs #9686

marcelgerber · 2014-10-26T18:26:49Z

Finally got a fix for #6027.
Updated css.json to include the latest data using this Node script.

The only remaining issue (which has existed before): The values are not in any useful order.

Changes (properties added/removed): https://gist.github.com/MarcelGerber/bfdd47849cf58c90a5cd

Mark-Simulacrum · 2014-10-26T19:37:27Z

src/extensions/default/WebPlatformDocs/update-docs/update-docs.js

+        res.on("end", function () {
+            console.log("Parsing properties");
+            propertiesResponse = JSON.parse(propertiesResponse).query.results;
+            Object.keys(propertiesResponse).forEach(function (propertyName) {


Since you already include lodash.unescape, why not depend on lodash itself and use it's forEach method?

Well, it doesn't give us much and I included lodash.unescape only as it's pretty lightweight (81KB vs 853KB for lodash-node).

I see your point. Probably doesn't matter too much in either case (this script won't be run very often, I would assume.)

marcelgerber · 2014-10-26T20:04:19Z

Forgot to mention: This also updates all URLs from http:// to https:// (while they are currently auto-redirected). Not a big thing, but worth a mention.

Mark-Simulacrum · 2014-10-26T21:20:35Z

Not sure if this is something to do with your script, but I found that opening Quick Docs on the CSS flex property has an odd heading, that looks like this:

<[[css/properties/flex-grow|flex-grow]]> <[[css/properties/flex-shrink|flex-shrink]]> <[[css/properties/flex-basis|flex-basis]]>

and is supposed to look like this, with each item being a link.

<flex-grow> <flex-shrink> <flex-basis>

le717 · 2014-10-27T01:15:15Z

:D

marcelgerber · 2014-10-27T01:26:08Z

Oh damn. At least, I don't need lodash.unescape any more.
@Mark-Simulacrum I've fixed the bug you mentioned, and probably (hopefully) thousands more.

Mark-Simulacrum · 2014-10-27T01:42:13Z

Found another issue with the Inline Docs for the alignment-adjust property. The values of the property are empty in the downloaded file; here is the JSON for it:

"css\/properties\/alignment-adjust": {
            "SUMMARY": "",
            "INITIALVALUE": "",
            "ID": "css\/properties\/alignment-adjust",
            "ANIMATABLE": false,
            "COMPUTEDVALUE": "",
            "URL": "http:\/\/docs.webplatform.org\/wiki\/css\/properties\/alignment-adjust",
            "STATUS": "",
            "VALUES": [

            ]
        }

The Docs display just the title and nothing else, I would expect them to not appear at all.

marcelgerber · 2014-10-27T02:00:48Z

@Mark-Simulacrum Your JSON snippet is part of the old file ;) But you're right, there are such cases with the updated file as well, like for css/properties/behavior. I did this on purpose as call to map() in InlineDocsViewer.js expects VALUES to be an array, but it's probably better to just add a condition there.

PS: Thanks for taking a look!

Mark-Simulacrum · 2014-10-27T02:09:02Z

Is it intentional that the (new) JSON file has a space after every TITLE string? (e.g."TITLE": "justify ").

Mark-Simulacrum · 2014-10-27T02:10:14Z

Actually, upon further inspection, every string in the file ends with a space. Is this something in update-docs.js?

marcelgerber · 2014-10-27T02:16:24Z

It's something instaview (the Wikitext parser) does. But I have to admit, I actually like it as it somehow makes Brackets way faster when viewing that file, probably due to Word Wrap being less performances heavy.

Mark-Simulacrum · 2014-10-27T02:18:03Z

Here is a few more bugs, will update this list as I go along to prevent posting too many comments:

Many (if not all) summaries/descriptions start with <p> but the paragraph tag is not closed.
animation-fill-mode property, see forwards value section; rendering has {| class="mw-datatable os-suggest-results filehistory", seems out of place.

marcelgerber · 2014-10-27T14:02:20Z

@Mark-Simulacrum A closing <p> tag is not required (see http://stackoverflow.com/questions/8460993/p-end-tag-p-is-not-needed-in-html), and InstaView omits it therefore.
The table bug is fixed, but our tables could use some design love.

marcelgerber · 2014-10-27T15:05:47Z

I just removed the extra step required to convert the JSON data to a usable format.

marcelgerber · 2014-10-27T19:35:46Z

src/extensions/default/WebPlatformDocs/InlineDocsViewer.js

@@ -49,19 +49,15 @@ define(function (require, exports, module) {

    /**
     * @param {!string} cssPropName
-     * @param {!{SUMMARY:string, URL:string, VALUES:Array.<{TITLE:string, DESCRIPTION:string}>}} cssPropDetails
+     * @param {!{SUMMARY:string, URL:string, VALUES:?Array.<{value:string, description:string}>}} cssPropDetails


For the JSDoc gurus: Is this (to be exact, the VALUES:?Array) valid?

redmunds · 2014-11-12T22:54:46Z

@marcelgerber Thanks for taking a look at this. Those docs are way out-of-date.

It looks like update-docs.js is a nodejs module with a dependency of instaview that updates the css.json file -- is that right? If so, that's an awesome contribution!

At the very least, the README.md file should mention that and also have a recipe for installing and running it. Since this code is never run by Brackets and introduces a new dependency, I'm thinking it should be in a separate repo outside of Brackets, but I'm open to other opinions. Moving it to a separate repo would also make it much easier to get the changes into css.json into Brackets.

marcelgerber · 2014-11-13T15:09:43Z

Yep, the ‘update-docs.js‘ is a node script to update the css.json file using the WebPlatformDocs/MediaWiki API.
I'm not quite sure whether it belongs in the brackets repo or not - it's basically a maintenance script, and other maintenance helpers like set-release are in the brackets repo as well.
Talking of set-release, I could imagine a similar workflow with update-docs as well - running it every time a new Release is set would be great, to keep the docs up to date.

redmunds · 2014-11-13T15:33:47Z

@marcelgerber I didn't think about the Tools folder -- I was thinking about the Apify nodejs app for creating Brackets API docs which is at: https://github.com/jbalsas/apify

marcelgerber · 2014-11-13T18:07:50Z

@redmunds I've completely removed the Node script and took it over to https://github.com/MarcelGerber/update-wpd-docs.
I've created a README with update instructions as well.

redmunds · 2014-11-13T23:20:43Z

I am seeing a WebPlatformDocs unit test fail:

should process all anchor tags

Error: Expected 1 to be 9.
    at new jasmine.ExpectationResult (file:///C:/Users/redmunds/dev/github/brackets-shell/Release/dev/test/thirdparty/jasmine-core/jasmine.js:114:32)
    at null.toBe (file:///C:/Users/redmunds/dev/github/brackets-shell/Release/dev/test/thirdparty/jasmine-core/jasmine.js:1235:29)
    at null.<anonymous> (file:///C:/Users/redmunds/dev/github/brackets-shell/Release/dev/src/extensions/default/WebPlatformDocs/unittests.js:210:39)
    at jasmine.Block.execute (file:///C:/Users/redmunds/dev/github/brackets-shell/Release/dev/test/thirdparty/jasmine-core/jasmine.js:1064:17)
    at jasmine.Queue.next_ (file:///C:/Users/redmunds/dev/github/brackets-shell/Release/dev/test/thirdparty/jasmine-core/jasmine.js:2096:31)
    at jasmine.Queue.start (file:///C:/Users/redmunds/dev/github/brackets-shell/Release/dev/test/thirdparty/jasmine-core/jasmine.js:2049:8)
    at jasmine.Spec.execute (file:///C:/Users/redmunds/dev/github/brackets-shell/Release/dev/test/thirdparty/jasmine-core/jasmine.js:2376:14)
    at jasmine.Queue.next_ (file:///C:/Users/redmunds/dev/github/brackets-shell/Release/dev/test/thirdparty/jasmine-core/jasmine.js:2096:31)
    at jasmine.Queue.start (file:///C:/Users/redmunds/dev/github/brackets-shell/Release/dev/test/thirdparty/jasmine-core/jasmine.js:2049:8)
    at jasmine.Suite.execute (file:///C:/Users/redmunds/dev/github/brackets-shell/Release/dev/test/thirdparty/jasmine-core/jasmine.js:2521:14)
    at jasmine.Queue.next_ (file:///C:/Users/redmunds/dev/github/brackets-shell/Release/dev/test/thirdparty/jasmine-core/jasmine.js:2096:31)

redmunds · 2014-11-13T23:45:10Z

-ms-flex-pack is the only vendor-specific property -- should it be removed?

marcelgerber · 2014-11-14T14:40:26Z

@redmunds Fixed the unit tests and removed the vendor-prefixed property.

redmunds · 2014-11-14T16:26:53Z

Thanks. Merging.

Update Web Platform Docs

marcelgerber force-pushed the update-wpd-docs branch from 31106b7 to f315f25 Compare October 26, 2014 18:30

Mark-Simulacrum reviewed Oct 26, 2014
View reviewed changes

marcelgerber force-pushed the update-wpd-docs branch from 77bb2d9 to c1aa04d Compare October 27, 2014 01:23

marcelgerber reviewed Oct 27, 2014
View reviewed changes

Update Web Platform Docs

d0bb9fa

marcelgerber force-pushed the update-wpd-docs branch from 89e0ebd to d0bb9fa Compare November 13, 2014 18:02

Create README with update instructions

2a19ede

marcelgerber changed the title ~~Update Web Platform Docs & Provide Update Script~~ Update Web Platform Docs Nov 13, 2014

Marcel Gerber added 2 commits November 14, 2014 14:54

Fixed unit test

17ebe58

Remove vendor-prefixed properties

fe0b27a

redmunds added a commit that referenced this pull request Nov 14, 2014

Merge pull request #9686 from MarcelGerber/update-wpd-docs

57dcc1a

Update Web Platform Docs

redmunds merged commit 57dcc1a into adobe:master Nov 14, 2014

marcelgerber deleted the update-wpd-docs branch November 14, 2014 17:09

marcelgerber mentioned this pull request Nov 14, 2014

Quick Docs inline editor for some font properties cannot be opened (Quick Docs are out of date) #6027

Closed

marcelgerber mentioned this pull request Nov 24, 2014

Quick Docs for HTML #9566

Closed

marcelgerber mentioned this pull request Jan 18, 2015

[PM] Cleanup WebPlatformDocs css.json #3471

Closed

This was referenced Aug 30, 2021

[CLOSED] Quick Docs for HTML brackets-archive/bracketsIssues#8538

Open

[CLOSED] Update Web Platform Docs brackets-archive/bracketsIssues#8623

Open

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Update Web Platform Docs #9686

Update Web Platform Docs #9686

marcelgerber commented Oct 26, 2014

Mark-Simulacrum Oct 26, 2014

marcelgerber Oct 26, 2014

Mark-Simulacrum Oct 26, 2014

marcelgerber commented Oct 26, 2014

Mark-Simulacrum commented Oct 26, 2014

le717 commented Oct 27, 2014

marcelgerber commented Oct 27, 2014

Mark-Simulacrum commented Oct 27, 2014

marcelgerber commented Oct 27, 2014

Mark-Simulacrum commented Oct 27, 2014

Mark-Simulacrum commented Oct 27, 2014

marcelgerber commented Oct 27, 2014

Mark-Simulacrum commented Oct 27, 2014

marcelgerber commented Oct 27, 2014

marcelgerber commented Oct 27, 2014

marcelgerber Oct 27, 2014

redmunds commented Nov 12, 2014

marcelgerber commented Nov 13, 2014

redmunds commented Nov 13, 2014

marcelgerber commented Nov 13, 2014

redmunds commented Nov 13, 2014

redmunds commented Nov 13, 2014

marcelgerber commented Nov 14, 2014

redmunds commented Nov 14, 2014

Update Web Platform Docs #9686

Update Web Platform Docs #9686

Conversation

marcelgerber commented Oct 26, 2014

Mark-Simulacrum Oct 26, 2014

Choose a reason for hiding this comment

marcelgerber Oct 26, 2014

Choose a reason for hiding this comment

Mark-Simulacrum Oct 26, 2014

Choose a reason for hiding this comment

marcelgerber commented Oct 26, 2014

Mark-Simulacrum commented Oct 26, 2014

le717 commented Oct 27, 2014

marcelgerber commented Oct 27, 2014

Mark-Simulacrum commented Oct 27, 2014

marcelgerber commented Oct 27, 2014

Mark-Simulacrum commented Oct 27, 2014

Mark-Simulacrum commented Oct 27, 2014

marcelgerber commented Oct 27, 2014

Mark-Simulacrum commented Oct 27, 2014

marcelgerber commented Oct 27, 2014

marcelgerber commented Oct 27, 2014

marcelgerber Oct 27, 2014

Choose a reason for hiding this comment

redmunds commented Nov 12, 2014

marcelgerber commented Nov 13, 2014

redmunds commented Nov 13, 2014

marcelgerber commented Nov 13, 2014

redmunds commented Nov 13, 2014

redmunds commented Nov 13, 2014

marcelgerber commented Nov 14, 2014

redmunds commented Nov 14, 2014