doc: use blockquotes for Stability: markers#7757
Uh oh!
There was an error while loading. Please reload this page.
Conversation
addaleax added doc 
addaleax commented Jul 15, 2016
CI: https://ci.nodejs.org/job/node-test-commit/4130/ /cc @ChALkeR @nodejs/documentation |
doc/api/documentation.md Outdated
| > Stability: 3 - Locked | ||
| > Only fixes related to security, performance, or bug fixes will be accepted. | ||
| > Please do not suggest API changes in this area; they will be refused. |
There was a problem hiding this comment.
This block doesn't look good on GitHub:
- This is interpreted as one blockquote, not four.
- Line breaks don't work.
Adding a manual line break there to fix how it looks on GitHub confuses the doc tool and it treats those as separated blocks, with only the first line being colored.
ChALkeR commented Jul 16, 2016
Also, this change added extra margin to the stability markers in the html produced by the doc tool by wrapping these As for the |
Nice, thanks! Just noticed: not sure why, but I have an |
addaleax commented Jul 17, 2016
@ChALkeR Thanks for noticing! Should be fixed now. |
jasnell commented Jul 20, 2016
LGTM |
@addaleax Something looks strange in the json output to me. {"textRaw": "fs.existsSync(path)", "type": "method", "name": "existsSync", "meta":{"added": [ "v0.1.21" ], "deprecated": [ "v1.0.0" ] }, "desc": "<p>Stability: 0 - Deprecated: Use [<code>fs.statSync()</code>][] or [<code>fs.accessSync()</code>][]\ninstead.</p>\n<p>Synchronous version of [<code>fs.exists()</code>][].\nReturns <code>true</code> if the file exists, <code>false</code> otherwise.</p>\n", "signatures": [{"params": [{"textRaw": "`path`{String | Buffer} ", "name": "path", "type": "String | Buffer" } ] },{"params": [{"name": "path" } ] } ] },Why are there two |
addaleax commented Jul 20, 2016
Yeah, I was planning on double-checking the JSON output anyway, sorry. |
doc/api/domain.md Outdated
There was a problem hiding this comment.
The next line also should be converted to > or at least the padding should be removed. Else, this is how it renders:
Note: this also changes JSON output from being wrapped into Also, it now generates things like |
Markdown — LGTM with one comment in |
addaleaxforce-pushed the doc-blockquote-stability branch from 29870ca to 5741399Compareaddaleax commented Jul 25, 2016
Rebased, and fixed the docs nit. I’ll have to look into the JSON output myself, that one’s confusing… you’re right, there’s a difference here, but it looks like this change actually resulted in prepending the correct signature information where it was previously left out. |
HTML output and *.md changes — LGTM /cc @nodejs/documentation again, @eljefedelrodeodeljefe, @silverwind, @firedfox. Actual output changes here — https://gist.github.com/ChALkeR/9fc933caa0faca63ba5105b9bc453ec2. |
ChALkeR commented Aug 3, 2016
/cc @nodejs/collaborators |
targos commented Aug 3, 2016
LGTM |
silverwind commented Aug 3, 2016
Got some screenshots of the docs before/after? (sorry for being so lazy) |
@silverwind There are no actual changes in the generated html except for a bugfix of https://nodejs.org/api/repl.html#repl_node_repl_history_file, see the diff linked at #7757 (comment) — so no other visual changes there. GitHub render changes could be viewed by comparing https://github.com/nodejs/node/blob/master/doc/api/tls.md#deprecated-apis with https://github.com/addaleax/node/blob/doc-blockquote-stability/doc/api/tls.md#deprecated-apis, for example. Screenshotting JSON output is pretty pointless. 😉 |
addaleax commented Aug 3, 2016
Yeah, screenshots don’t really make sense here, and apart from that @ChALkeR’s diff is probably the best one can get for the JSON output. That one does look okay to me. |
Thanks. JSON looks more correct than before at least. LGTM. |
Use blockquotes instead of code blocks for stability markers in the docs. Doing that: - Makes the makers appear correctly when viewed e.g. on github. - Allows remark-lint rules like `no-undefined-references` to work properly (nodejs#7729).
addaleaxforce-pushed the doc-blockquote-stability branch from 5741399 to 67c77efCompareaddaleax commented Aug 3, 2016
Rebased to resolve conflict with 29e49fc, new CI: https://ci.nodejs.org/job/node-test-commit/4393/ I’d like to land this if it’s green. |
jasnell commented Aug 4, 2016
This still LGTM. Is this ready to go? |
addaleax commented Aug 4, 2016
Yes, I’ll land it now (thanks for the ping!) |
Use blockquotes instead of code blocks for stability markers in the docs. Doing that: - Makes the makers appear correctly when viewed e.g. on github. - Allows remark-lint rules like `no-undefined-references` to work properly (#7729). PR-URL: #7757 Reviewed-By: James M Snell <[email protected]> Reviewed-By: Сковорода Никита Андреевич <[email protected]> Reviewed-By: Michaël Zasso <[email protected]> Reviewed-By: Roman Reiss <[email protected]>
addaleax commented Aug 4, 2016
Landed in c809b88, thanks for the reviews everyone! |
Specifies the configuration for remark-lint, a markdown linter. This configuration does not cause any warnings on any of the currently present *.md files (ignoring thirdparty). It is useful not only for possible future tooling that would check the markdown files syntax, but also as a configuration for editor plugins, e.g. linter-markdown for atom-linter. Refs: nodejs#7637 Refs: nodejs#7727 Refs: nodejs#7757 PR-URL: nodejs#7729 Reviewed-By: Colin Ihrig <[email protected]> Reviewed-By: Rich Trott <[email protected]> Reviewed-By: James M Snell <[email protected]> Reviewed-By: Anna Henningsen <[email protected]> Reviewed-By: Robert Jefe Lindstaedt <[email protected]>
Use blockquotes instead of code blocks for stability markers in the docs. Doing that: - Makes the makers appear correctly when viewed e.g. on github. - Allows remark-lint rules like `no-undefined-references` to work properly (#7729). PR-URL: #7757 Reviewed-By: James M Snell <[email protected]> Reviewed-By: Сковорода Никита Андреевич <[email protected]> Reviewed-By: Michaël Zasso <[email protected]> Reviewed-By: Roman Reiss <[email protected]> Conflicts: doc/api/punycode.md
Specifies the configuration for remark-lint, a markdown linter. This configuration does not cause any warnings on any of the currently present *.md files (ignoring thirdparty). It is useful not only for possible future tooling that would check the markdown files syntax, but also as a configuration for editor plugins, e.g. linter-markdown for atom-linter. Refs: #7637 Refs: #7727 Refs: #7757 PR-URL: #7729 Reviewed-By: Colin Ihrig <[email protected]> Reviewed-By: Rich Trott <[email protected]> Reviewed-By: James M Snell <[email protected]> Reviewed-By: Anna Henningsen <[email protected]> Reviewed-By: Robert Jefe Lindstaedt <[email protected]>
Specifies the configuration for remark-lint, a markdown linter. This configuration does not cause any warnings on any of the currently present *.md files (ignoring thirdparty). It is useful not only for possible future tooling that would check the markdown files syntax, but also as a configuration for editor plugins, e.g. linter-markdown for atom-linter. Refs: #7637 Refs: #7727 Refs: #7757 PR-URL: #7729 Reviewed-By: Colin Ihrig <[email protected]> Reviewed-By: Rich Trott <[email protected]> Reviewed-By: James M Snell <[email protected]> Reviewed-By: Anna Henningsen <[email protected]> Reviewed-By: Robert Jefe Lindstaedt <[email protected]>
Specifies the configuration for remark-lint, a markdown linter. This configuration does not cause any warnings on any of the currently present *.md files (ignoring thirdparty). It is useful not only for possible future tooling that would check the markdown files syntax, but also as a configuration for editor plugins, e.g. linter-markdown for atom-linter. Refs: #7637 Refs: #7727 Refs: #7757 PR-URL: #7729 Reviewed-By: Colin Ihrig <[email protected]> Reviewed-By: Rich Trott <[email protected]> Reviewed-By: James M Snell <[email protected]> Reviewed-By: Anna Henningsen <[email protected]> Reviewed-By: Robert Jefe Lindstaedt <[email protected]>
MylesBorins commented Sep 30, 2016
@addaleax this is not landing cleanly, likely due to a bunch of other commits needing to be backported. please feel free to manually backport |
Use blockquotes instead of code blocks for stability markers in the docs. Doing that: - Makes the makers appear correctly when viewed e.g. on github. - Allows remark-lint rules like `no-undefined-references` to work properly (nodejs#7729). PR-URL: nodejs#7757 Reviewed-By: James M Snell <[email protected]> Reviewed-By: Сковорода Никита Андреевич <[email protected]> Reviewed-By: Michaël Zasso <[email protected]> Reviewed-By: Roman Reiss <[email protected]>
Use blockquotes instead of code blocks for stability markers in the docs. Doing that: - Makes the makers appear correctly when viewed e.g. on github. - Allows remark-lint rules like `no-undefined-references` to work properly (#7729). PR-URL: #7757 Reviewed-By: James M Snell <[email protected]> Reviewed-By: Сковорода Никита Андреевич <[email protected]> Reviewed-By: Michaël Zasso <[email protected]> Reviewed-By: Roman Reiss <[email protected]>
Use blockquotes instead of code blocks for stability markers in the docs. Doing that: - Makes the makers appear correctly when viewed e.g. on github. - Allows remark-lint rules like `no-undefined-references` to work properly (#7729). PR-URL: #7757 Reviewed-By: James M Snell <[email protected]> Reviewed-By: Сковорода Никита Андреевич <[email protected]> Reviewed-By: Michaël Zasso <[email protected]> Reviewed-By: Roman Reiss <[email protected]>
Use blockquotes instead of code blocks for stability markers in the docs. Doing that: - Makes the makers appear correctly when viewed e.g. on github. - Allows remark-lint rules like `no-undefined-references` to work properly (#7729). PR-URL: #7757 Reviewed-By: James M Snell <[email protected]> Reviewed-By: Сковорода Никита Андреевич <[email protected]> Reviewed-By: Michaël Zasso <[email protected]> Reviewed-By: Roman Reiss <[email protected]>
Specifies the configuration for remark-lint, a markdown linter. This configuration does not cause any warnings on any of the currently present *.md files (ignoring thirdparty). It is useful not only for possible future tooling that would check the markdown files syntax, but also as a configuration for editor plugins, e.g. linter-markdown for atom-linter. Refs: #7637 Refs: #7727 Refs: #7757 PR-URL: #7729 Reviewed-By: Colin Ihrig <[email protected]> Reviewed-By: Rich Trott <[email protected]> Reviewed-By: James M Snell <[email protected]> Reviewed-By: Anna Henningsen <[email protected]> Reviewed-By: Robert Jefe Lindstaedt <[email protected]>
Use blockquotes instead of code blocks for stability markers in the docs. Doing that: - Makes the makers appear correctly when viewed e.g. on github. - Allows remark-lint rules like `no-undefined-references` to work properly (#7729). PR-URL: #7757 Reviewed-By: James M Snell <[email protected]> Reviewed-By: Сковорода Никита Андреевич <[email protected]> Reviewed-By: Michaël Zasso <[email protected]> Reviewed-By: Roman Reiss <[email protected]>
Specifies the configuration for remark-lint, a markdown linter. This configuration does not cause any warnings on any of the currently present *.md files (ignoring thirdparty). It is useful not only for possible future tooling that would check the markdown files syntax, but also as a configuration for editor plugins, e.g. linter-markdown for atom-linter. Refs: #7637 Refs: #7727 Refs: #7757 PR-URL: #7729 Reviewed-By: Colin Ihrig <[email protected]> Reviewed-By: Rich Trott <[email protected]> Reviewed-By: James M Snell <[email protected]> Reviewed-By: Anna Henningsen <[email protected]> Reviewed-By: Robert Jefe Lindstaedt <[email protected]>
Use blockquotes instead of code blocks for stability markers in the docs. Doing that: - Makes the makers appear correctly when viewed e.g. on github. - Allows remark-lint rules like `no-undefined-references` to work properly (#7729). PR-URL: #7757 Reviewed-By: James M Snell <[email protected]> Reviewed-By: Сковорода Никита Андреевич <[email protected]> Reviewed-By: Michaël Zasso <[email protected]> Reviewed-By: Roman Reiss <[email protected]>
6 participants
Use blockquotes instead of code blocks for stability markers in
the docs. Doing that:
no-undefined-referencesto workproperly (tools: add remark-lint configuration in .remarkrc #7729).