doc: use blockquotes for Stability: markers #7757

addaleax · 2016-07-15T22:46:35Z

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 (tools: add remark-lint configuration in .remarkrc #7729).

addaleax · 2016-07-15T22:48:01Z

CI: https://ci.nodejs.org/job/node-test-commit/4130/

/cc @ChALkeR @nodejs/documentation

ChALkeR · 2016-07-16T11:31:05Z

doc/api/documentation.md

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


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 · 2016-07-16T11:35:58Z

Also, this change added extra margin to the stability markers in the html produced by the doc tool by wrapping these <pre> blocks in a blockquote. Can we somehow get rid of the blockquote or change its style?

As for the documentation.md changes — perhaps it would make sense to support both ways (code block and blockquote) and use the code block only in the documentation.md file?

ChALkeR · 2016-07-16T23:41:52Z

Nice, thanks!

Just noticed: not sure why, but I have an "undefined" Text node under each stability level blockquote in the generated HTML =). That doesn't affect the stability code blocks in documentation.md.

addaleax · 2016-07-17T15:04:22Z

@ChALkeR Thanks for noticing! Should be fixed now.

jasnell · 2016-07-20T16:09:05Z

LGTM

ChALkeR · 2016-07-20T16:55:14Z

@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 signatures there now?

addaleax · 2016-07-20T16:57:38Z

Yeah, I was planning on double-checking the JSON output anyway, sorry.

ChALkeR · 2016-07-20T17:04:48Z

doc/api/domain.md

@@ -436,7 +436,7 @@ without exiting the domain.

 ### domain.dispose()

-    Stability: 0 - Deprecated.  Please recover from failed IO actions
+> Stability: 0 - Deprecated.  Please recover from failed IO actions


The next line also should be converted to > or at least the padding should be removed. Else, this is how it renders:

ChALkeR · 2016-07-20T17:19:14Z

Note: this also changes JSON output from being wrapped into <pre><code> into being wrapped into <p>. I'm not saying that it's a bad thing — I don't know =).

Also, it now generates things like [<code>fs.accessSync()</code>][] instead of [fs.accessSync()][] (in the JSON). Btw, I'm not sure if [fs.accessSync()][] is correct there, shouldn't it be a link, as everything looks html-ish there? I'm not familiar with the json output.

ChALkeR · 2016-07-20T17:22:44Z

Markdown — LGTM with one comment in domain.md.
HTML — LGTM.
JSON — some comments above, but I'm not sure about most of those myself, so it shouldn't block this.

addaleax · 2016-07-25T07:43:52Z

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.

ChALkeR · 2016-07-25T09:19:55Z

HTML output and *.md changes — LGTM
JSON — looks reasonable, but again — I'm not familiar with json output.

/cc @nodejs/documentation again, @eljefedelrodeodeljefe, @silverwind, @firedfox.

Actual output changes here — https://gist.github.com/ChALkeR/9fc933caa0faca63ba5105b9bc453ec2.
HTML change (first file) is fine, that's just due to #7757 (comment) bugfix.

ChALkeR · 2016-08-03T09:05:42Z

/cc @nodejs/collaborators

targos · 2016-08-03T11:52:37Z

LGTM

silverwind · 2016-08-03T13:25:32Z

Got some screenshots of the docs before/after? (sorry for being so lazy)

ChALkeR · 2016-08-03T15:14:04Z

@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 · 2016-08-03T15:42:43Z

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.

silverwind · 2016-08-03T16:34:57Z

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

addaleax · 2016-08-03T18:11:40Z

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 · 2016-08-04T20:40:49Z

This still LGTM. Is this ready to go?

addaleax · 2016-08-04T20:42:01Z

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 <jasnell@gmail.com> Reviewed-By: Сковорода Никита Андреевич <chalkerx@gmail.com> Reviewed-By: Michaël Zasso <mic.besace@gmail.com> Reviewed-By: Roman Reiss <me@silverwind.io>

addaleax · 2016-08-04T21:31:42Z

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 <cjihrig@gmail.com> Reviewed-By: Rich Trott <rtrott@gmail.com> Reviewed-By: James M Snell <jasnell@gmail.com> Reviewed-By: Anna Henningsen <anna@addaleax.net> Reviewed-By: Robert Jefe Lindstaedt <robert.lindstaedt@gmail.com>

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 <jasnell@gmail.com> Reviewed-By: Сковорода Никита Андреевич <chalkerx@gmail.com> Reviewed-By: Michaël Zasso <mic.besace@gmail.com> Reviewed-By: Roman Reiss <me@silverwind.io> 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 <cjihrig@gmail.com> Reviewed-By: Rich Trott <rtrott@gmail.com> Reviewed-By: James M Snell <jasnell@gmail.com> Reviewed-By: Anna Henningsen <anna@addaleax.net> Reviewed-By: Robert Jefe Lindstaedt <robert.lindstaedt@gmail.com>

MylesBorins · 2016-09-30T17:57:26Z

@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 <jasnell@gmail.com> Reviewed-By: Сковорода Никита Андреевич <chalkerx@gmail.com> Reviewed-By: Michaël Zasso <mic.besace@gmail.com> Reviewed-By: Roman Reiss <me@silverwind.io>

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 <jasnell@gmail.com> Reviewed-By: Сковорода Никита Андреевич <chalkerx@gmail.com> Reviewed-By: Michaël Zasso <mic.besace@gmail.com> Reviewed-By: Roman Reiss <me@silverwind.io>

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 <cjihrig@gmail.com> Reviewed-By: Rich Trott <rtrott@gmail.com> Reviewed-By: James M Snell <jasnell@gmail.com> Reviewed-By: Anna Henningsen <anna@addaleax.net> Reviewed-By: Robert Jefe Lindstaedt <robert.lindstaedt@gmail.com>

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 <jasnell@gmail.com> Reviewed-By: Сковорода Никита Андреевич <chalkerx@gmail.com> Reviewed-By: Michaël Zasso <mic.besace@gmail.com> Reviewed-By: Roman Reiss <me@silverwind.io>

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 <cjihrig@gmail.com> Reviewed-By: Rich Trott <rtrott@gmail.com> Reviewed-By: James M Snell <jasnell@gmail.com> Reviewed-By: Anna Henningsen <anna@addaleax.net> Reviewed-By: Robert Jefe Lindstaedt <robert.lindstaedt@gmail.com>

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 <jasnell@gmail.com> Reviewed-By: Сковорода Никита Андреевич <chalkerx@gmail.com> Reviewed-By: Michaël Zasso <mic.besace@gmail.com> Reviewed-By: Roman Reiss <me@silverwind.io>

addaleax added doc Issues and PRs related to the documentations. tools Issues and PRs related to the tools directory. labels Jul 15, 2016

ChALkeR reviewed Jul 16, 2016
View reviewed changes

addaleax added the wip Issues and PRs that are still a work in progress. label Jul 20, 2016

ChALkeR reviewed Jul 20, 2016
View reviewed changes

addaleax removed the wip Issues and PRs that are still a work in progress. label Jul 25, 2016

addaleax force-pushed the doc-blockquote-stability branch from 29870ca to 5741399 Compare July 25, 2016 07:41

doc: use blockquotes for Stability: markers

67c77ef

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

addaleax force-pushed the doc-blockquote-stability branch from 5741399 to 67c77ef Compare August 3, 2016 18:10

ChALkeR mentioned this pull request Aug 4, 2016

tools: add remark-lint configuration in .remarkrc #7729

Merged

1 task

addaleax closed this Aug 4, 2016

addaleax deleted the doc-blockquote-stability branch August 4, 2016 21:31

cjihrig mentioned this pull request Aug 8, 2016

v6.4.0 Release Proposal #8020

Closed

cjihrig mentioned this pull request Aug 11, 2016

v6.4.0 Proposal #8070

Merged

MylesBorins added the dont-land-on-v4.x label Sep 30, 2016

addaleax mentioned this pull request Sep 30, 2016

v4.x backport: doc: use blockquotes for Stability: markers #8868

Closed

MylesBorins mentioned this pull request Oct 26, 2016

V4.6.2 proposal #9298

Closed

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

doc: use blockquotes for Stability: markers #7757

doc: use blockquotes for Stability: markers #7757

addaleax commented Jul 15, 2016

addaleax commented Jul 15, 2016

ChALkeR Jul 16, 2016 •

edited

Loading

ChALkeR commented Jul 16, 2016

ChALkeR commented Jul 16, 2016 •

edited

Loading

addaleax commented Jul 17, 2016

jasnell commented Jul 20, 2016

ChALkeR commented Jul 20, 2016 •

edited

Loading

addaleax commented Jul 20, 2016

ChALkeR Jul 20, 2016

ChALkeR commented Jul 20, 2016 •

edited

Loading

ChALkeR commented Jul 20, 2016 •

edited

Loading

addaleax commented Jul 25, 2016

ChALkeR commented Jul 25, 2016 •

edited

Loading

ChALkeR commented Aug 3, 2016

targos commented Aug 3, 2016

silverwind commented Aug 3, 2016

ChALkeR commented Aug 3, 2016 •

edited

Loading

addaleax commented Aug 3, 2016

silverwind commented Aug 3, 2016 •

edited

Loading

addaleax commented Aug 3, 2016

jasnell commented Aug 4, 2016

addaleax commented Aug 4, 2016

addaleax commented Aug 4, 2016

MylesBorins commented Sep 30, 2016

doc: use blockquotes for Stability: markers #7757

doc: use blockquotes for Stability: markers #7757

Conversation

addaleax commented Jul 15, 2016

addaleax commented Jul 15, 2016

ChALkeR Jul 16, 2016 • edited Loading

Choose a reason for hiding this comment

ChALkeR commented Jul 16, 2016

ChALkeR commented Jul 16, 2016 • edited Loading

addaleax commented Jul 17, 2016

jasnell commented Jul 20, 2016

ChALkeR commented Jul 20, 2016 • edited Loading

addaleax commented Jul 20, 2016

ChALkeR Jul 20, 2016

Choose a reason for hiding this comment

ChALkeR commented Jul 20, 2016 • edited Loading

ChALkeR commented Jul 20, 2016 • edited Loading

addaleax commented Jul 25, 2016

ChALkeR commented Jul 25, 2016 • edited Loading

ChALkeR commented Aug 3, 2016

targos commented Aug 3, 2016

silverwind commented Aug 3, 2016

ChALkeR commented Aug 3, 2016 • edited Loading

addaleax commented Aug 3, 2016

silverwind commented Aug 3, 2016 • edited Loading

addaleax commented Aug 3, 2016

jasnell commented Aug 4, 2016

addaleax commented Aug 4, 2016

addaleax commented Aug 4, 2016

MylesBorins commented Sep 30, 2016

ChALkeR Jul 16, 2016 •

edited

Loading

ChALkeR commented Jul 16, 2016 •

edited

Loading

ChALkeR commented Jul 20, 2016 •

edited

Loading

ChALkeR commented Jul 20, 2016 •

edited

Loading

ChALkeR commented Jul 20, 2016 •

edited

Loading

ChALkeR commented Jul 25, 2016 •

edited

Loading

ChALkeR commented Aug 3, 2016 •

edited

Loading

silverwind commented Aug 3, 2016 •

edited

Loading