doc: do not begin yaml value with backtick by maclover7 · Pull Request #15447 · nodejs/node · GitHub

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>' ```

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

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

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...

Should this wait 48 hours?

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

I will land then)

Will break YAML parsing! See details in the PR. PR-URL: #15447 Fixes: #14930 Reviewed-By: Refael Ackermann <refack@gmail.com> Reviewed-By: Anna Henningsen <anna@addaleax.net>

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.

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

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#15447 Fixes: nodejs/node#14930 Reviewed-By: Refael Ackermann <refack@gmail.com> Reviewed-By: Anna Henningsen <anna@addaleax.net>

Will break YAML parsing! See details in the PR. PR-URL: #15447 Fixes: #14930 Reviewed-By: Refael Ackermann <refack@gmail.com> Reviewed-By: Anna Henningsen <anna@addaleax.net>

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

doc: do not begin yaml value with backtick by maclover7 · Pull Request #15447 · nodejs/node · GitHub

Uh oh!

Uh oh!

doc: do not begin yaml value with backtick - #15447

doc: do not begin yaml value with backtick#15447
maclover7 wants to merge 1 commit into
nodejs:masterfrom
maclover7:jm-fix-doc

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

doc: do not begin yaml value with backtick by maclover7 · Pull Request #15447 · nodejs/node · GitHub

Uh oh!

Uh oh!

doc: do not begin yaml value with backtick - #15447

doc: do not begin yaml value with backtick#15447maclover7 wants to merge 1 commit intonodejs:masternodejs/node:masterfrom maclover7:jm-fix-docCopy head branch name to clipboard

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

doc: do not begin yaml value with backtick#15447
maclover7 wants to merge 1 commit into
nodejs:masterfrom
maclover7:jm-fix-doc