doc: do not begin yaml value with backtick#15447

maclover7 · 2017-09-17T15:38:39Z

Will break YAML parsing otherwise!

Full details about error:

Details

Original Node error:

Jonathans-MBP:node jon$ node tools/doc/generate.js --format=json doc/api/dgram.md Input file = doc/api/dgram.md{Error at generateError (/Users/jon/code/nodejs/node/tools/eslint/node_modules/js-yaml/lib/js-yaml/loader.js:165:10) at throwError (/Users/jon/code/nodejs/node/tools/eslint/node_modules/js-yaml/lib/js-yaml/loader.js:171:9) at readBlockSequence (/Users/jon/code/nodejs/node/tools/eslint/node_modules/js-yaml/lib/js-yaml/loader.js:935:7) at composeNode (/Users/jon/code/nodejs/node/tools/eslint/node_modules/js-yaml/lib/js-yaml/loader.js:1331:12) at readBlockMapping (/Users/jon/code/nodejs/node/tools/eslint/node_modules/js-yaml/lib/js-yaml/loader.js:1062:11) at composeNode (/Users/jon/code/nodejs/node/tools/eslint/node_modules/js-yaml/lib/js-yaml/loader.js:1332:12) at readDocument (/Users/jon/code/nodejs/node/tools/eslint/node_modules/js-yaml/lib/js-yaml/loader.js:1492:3) at loadDocuments (/Users/jon/code/nodejs/node/tools/eslint/node_modules/js-yaml/lib/js-yaml/loader.js:1548:5) at load (/Users/jon/code/nodejs/node/tools/eslint/node_modules/js-yaml/lib/js-yaml/loader.js:1569:19) at Object.safeLoad (/Users/jon/code/nodejs/node/tools/eslint/node_modules/js-yaml/lib/js-yaml/loader.js:1591:10) name: 'YAMLException', reason: 'bad indentation of a sequence entry', mark: Mark{name: null, buffer: '\nadded: v0.11.13\nchanges:\n - version: REPLACEME\n pr-url: https://github.com/nodejs/node/pull/14560\n description: The `lookup` option is supported.\n - version: REPLACEME\n pr-url: https://github.com/nodejs/node/pull/13623\n description: `recvBufferSize` and `sendBufferSize` options are supported now.\n\u0000', position: 248, line: 8, column: 17 }, message: 'bad indentation of a sequence entry at line 9, column 18:\n description: `recvBufferSize` and `sendBuffer ... \n ^' }

Then I extracted out the problematic YAML, and tried running through Ruby as a
separate .yml file:

Psych::SyntaxError: (<unknown>): found character that cannot start any token while scanning for the next token at line 8 column 18 from /Users/jon/.rbenv/versions/2.4.0/lib/ruby/2.4.0/psych.rb:377:in `parse' from /Users/jon/.rbenv/versions/2.4.0/lib/ruby/2.4.0/psych.rb:377:in `parse_stream' from /Users/jon/.rbenv/versions/2.4.0/lib/ruby/2.4.0/psych.rb:325:in `parse' from /Users/jon/.rbenv/versions/2.4.0/lib/ruby/2.4.0/psych.rb:252:in `load' from (irb):7 from /Users/jon/.rbenv/versions/2.4.0/bin/irb:11:in `<main>'

Not intimately familiar, but node-test-pull-request / node-test-commit should be compiling the docs somewhere along the line, right? 😬

Checklist

documentation is changed or added
commit message follows commit guidelines

Affected core subsystem(s)

doc

Will break YAML parsing! Original Node error: ``` Jonathans-MBP:node jon$ node tools/doc/generate.js --format=json doc/api/dgram.md Input file = doc/api/dgram.md{Error at generateError (/Users/jon/code/nodejs/node/tools/eslint/node_modules/js-yaml/lib/js-yaml/loader.js:165:10) at throwError (/Users/jon/code/nodejs/node/tools/eslint/node_modules/js-yaml/lib/js-yaml/loader.js:171:9) at readBlockSequence (/Users/jon/code/nodejs/node/tools/eslint/node_modules/js-yaml/lib/js-yaml/loader.js:935:7) at composeNode (/Users/jon/code/nodejs/node/tools/eslint/node_modules/js-yaml/lib/js-yaml/loader.js:1331:12) at readBlockMapping (/Users/jon/code/nodejs/node/tools/eslint/node_modules/js-yaml/lib/js-yaml/loader.js:1062:11) at composeNode (/Users/jon/code/nodejs/node/tools/eslint/node_modules/js-yaml/lib/js-yaml/loader.js:1332:12) at readDocument (/Users/jon/code/nodejs/node/tools/eslint/node_modules/js-yaml/lib/js-yaml/loader.js:1492:3) at loadDocuments (/Users/jon/code/nodejs/node/tools/eslint/node_modules/js-yaml/lib/js-yaml/loader.js:1548:5) at load (/Users/jon/code/nodejs/node/tools/eslint/node_modules/js-yaml/lib/js-yaml/loader.js:1569:19) at Object.safeLoad (/Users/jon/code/nodejs/node/tools/eslint/node_modules/js-yaml/lib/js-yaml/loader.js:1591:10) name: 'YAMLException', reason: 'bad indentation of a sequence entry', mark: Mark{name: null, buffer: '\nadded: v0.11.13\nchanges:\n - version: REPLACEME\n pr-url: https://github.com/nodejs/node/pull/14560\n description: The `lookup` option is supported.\n - version: REPLACEME\n pr-url: https://github.com/nodejs/node/pull/13623\n description: `recvBufferSize` and `sendBufferSize` options are supported now.\n\u0000', position: 248, line: 8, column: 17 }, message: 'bad indentation of a sequence entry at line 9, column 18:\n description: `recvBufferSize` and `sendBuffer ... \n ^' } ``` Then I extracted out the problematic YAML, and tried running through Ruby as a separate `.yml` file: ``` Psych::SyntaxError: (<unknown>): found character that cannot start any token while scanning for the next token at line 8 column 18 from /Users/jon/.rbenv/versions/2.4.0/lib/ruby/2.4.0/psych.rb:377:in `parse' from /Users/jon/.rbenv/versions/2.4.0/lib/ruby/2.4.0/psych.rb:377:in `parse_stream' from /Users/jon/.rbenv/versions/2.4.0/lib/ruby/2.4.0/psych.rb:325:in `parse' from /Users/jon/.rbenv/versions/2.4.0/lib/ruby/2.4.0/psych.rb:252:in `load' from (irb):7 from /Users/jon/.rbenv/versions/2.4.0/bin/irb:11:in `<main>' ```

refack · 2017-09-17T15:43:47Z

Nice work!

Not intimately familiar, but 1node-test-pull-request1 / 1node-test-commit1 should be compiling the docs somewhere along the line, right? 😬

Nope.
That's a very good test to add (running node tools/doc/generate.js), at first probably checking sanity, but later maybe validating some invariants, a la test-benckmark-*.js

vsemozhetbyt · 2017-09-17T15:50:50Z

Can this be handled by md linting? Maybe by some YAML plugin?

refack · 2017-09-17T15:57:48Z

Can this be handled by md linting? Maybe by some YAML plugin?

👍 that was my other thought, but IMHO anyway end2end testing of tools/doc/generate.js should happen as part of regular CI...

vsemozhetbyt · 2017-09-17T16:25:28Z

Should this wait 48 hours?

addaleax · 2017-09-17T16:26:40Z

@vsemozhetbyt I don’t think it needs to, no

vsemozhetbyt · 2017-09-17T16:27:21Z

I will land then)

Will break YAML parsing! See details in the PR. PR-URL: #15447Fixes: #14930 Reviewed-By: Refael Ackermann <[email protected]> Reviewed-By: Anna Henningsen <[email protected]>

vsemozhetbyt · 2017-09-17T16:36:14Z

Landed in 75f7b2f.
I've simplified the commit message, as all the details are in the PR.
Let's see if the docs appear in the nearest Nightly.

vsemozhetbyt · 2017-09-17T16:39:44Z

@maclover7 Thank you for finding out the cause and fixing!

vsemozhetbyt · 2017-09-17T19:40:15Z

Seems fixed: https://nodejs.org/download/nightly/v9.0.0-nightly2017091775f7b2f577/docs/api/

Will break YAML parsing! See details in the PR. PR-URL: nodejs/node#15447Fixes: nodejs/node#14930 Reviewed-By: Refael Ackermann <[email protected]> Reviewed-By: Anna Henningsen <[email protected]>

Will break YAML parsing! See details in the PR. PR-URL: #15447Fixes: #14930 Reviewed-By: Refael Ackermann <[email protected]> Reviewed-By: Anna Henningsen <[email protected]>

MylesBorins · 2017-10-17T19:12:13Z

commit that broke stuff didn't land on v6.x, setting this to do-not-land-v6.x, lmk if we should reconsider

nodejs-github-bot added dgram Issues and PRs related to the dgram subsystem / UDP. doc Issues and PRs related to the documentations. labels Sep 17, 2017

maclover7 mentioned this pull request Sep 17, 2017
Nightly docs missing #14930
Closed

refack approved these changes Sep 17, 2017
View reviewed changes

addaleax approved these changes Sep 17, 2017
View reviewed changes

vsemozhetbyt closed this Sep 17, 2017

maclover7 deleted the jm-fix-doc branch September 17, 2017 18:47

maclover7 mentioned this pull request Sep 17, 2017
node-test-commit: run make doc during tests nodejs/build#887
Closed

MylesBorins mentioned this pull request Oct 3, 2017
v8.7.0 proposal #15762
Merged

This was referenced Oct 5, 2017
doc: update fs.utimes{,Sync} changelog #15680
Closed
doc: fix cause of yaml parsing error #15788
Closed

MylesBorins added the dont-land-on-v6.x label Oct 17, 2017

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

Uh oh!

doc: do not begin yaml value with backtick#15447

doc: do not begin yaml value with backtick #15447

Uh oh!

maclover7 commented Sep 17, 2017

Uh oh!

refack commented Sep 17, 2017

Uh oh!

vsemozhetbyt commented Sep 17, 2017

Uh oh!

refack commented Sep 17, 2017

Uh oh!

vsemozhetbyt commented Sep 17, 2017

Uh oh!

addaleax commented Sep 17, 2017

Uh oh!

vsemozhetbyt commented Sep 17, 2017

Uh oh!

vsemozhetbyt commented Sep 17, 2017

Uh oh!

vsemozhetbyt commented Sep 17, 2017

Uh oh!

vsemozhetbyt commented Sep 17, 2017

Uh oh!

MylesBorins commented Oct 17, 2017

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

6 participants

Uh oh!

doc: do not begin yaml value with backtick#15447

doc: do not begin yaml value with backtick #15447

Uh oh!

Conversation

maclover7 commented Sep 17, 2017

Checklist

Affected core subsystem(s)

Uh oh!

refack commented Sep 17, 2017

Uh oh!

vsemozhetbyt commented Sep 17, 2017

Uh oh!

refack commented Sep 17, 2017

Uh oh!

vsemozhetbyt commented Sep 17, 2017

Uh oh!

addaleax commented Sep 17, 2017

Uh oh!

vsemozhetbyt commented Sep 17, 2017

Uh oh!

vsemozhetbyt commented Sep 17, 2017

Uh oh!

vsemozhetbyt commented Sep 17, 2017

Uh oh!

vsemozhetbyt commented Sep 17, 2017

Uh oh!

MylesBorins commented Oct 17, 2017

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

6 participants