tools: parse documentation metadata #3867
Conversation
|
LGTM |
|
@nodejs/documentation |
|
Could this possibly include examples in |
tflanagan
force-pushed
the
doc-parse-since-ver
branch
from
33f43dd
to
96ab818
Compare
|
@bengl, I've added examples /poke |
|
LGTM |
|
Hey, so I'm working on replacing our doctool with remark, hopefully sooner than later. Part of that work is going to be to parsing YAML metadata after headers, which could be used for this sort of thing. I just wanted to share that bit of info because this data seems like it'd fit well into YAML metadata, so it'd be good to keep that in mind. |
|
@Qard, looks like a format is still being debated? |
|
@tflanagan I think it's better to merge what you have here so folks can get started annotating the docs. We can change to the new YAML format later, once it's been solidified. |
|
It just occurred to me to ask this: does adding |
|
No,
|
|
+1 to getting this landed and incrementally improving from there. |
|
Some background: the direction we are planning on heading is to add per-section YAML data in an HTML comment below the section header — that way we can store all sorts of metadata about the section, including "since version" info. Concretely, this is what that would look like. In any case, we'll need the "since version" information annotated, but we might introduce a little extra churn if we go the So, I'm +1 on merging this as-is, with the knowledge that we may be revisiting docs that include |
|
sounds like a solid approach to me. btw, I've been wanting to join the docs wg discussions more but have been buried the past two weeks. I'm looking forward to seeing what more y'all have come up with so far. |
|
I'm also 👍 on this, just wanted to share some details on the doctool we're working on and how that will impact the content of this PR in the future. If you want to see what we're working on for the doctool, there's a tracking issue with a list of the parts we need to put together. 😸 |
|
Awesome, I'd love to get this landed too. But this requires some CSS to go along with it. I wasn't sure if that was something I should introduce or something that the Doc team would take care of, but as of right now, this PR would make the Docs look a bit off... |
|
That should likely be included in this PR then if possible.
|
|
The HTML API is rather constraining in terms of width... Which makes putting it next to either the hashtag static link or the method/prop/class/etc name a little hard. We either need to expand the width of the |
|
I was thinking for the YAML formatted stuff in the future doctool, it could put a block of stuff below the header. You could maybe try that here to start us in that direction. @nodejs/documentation Does that sound like a reasonable plan? |
|
@Qard, That's a good idea. I'll submit a solution by EOD |
tflanagan
force-pushed
the
doc-parse-since-ver
branch
2 times, most recently
from
ffcb651
to
19e0bc8
Compare
|
@jasnell, @Qard, so here's the first draft, pretty basic, but gets the concept out there. ## assert(value[, message]), assert.ok(value[, message])
<!-- YAML
stability: 0
added: v0.10.0
deprecated: v4.0.0
-->This implementation allows for and already supports any other metadata (stability, deprecated) you wish to add.
I've also, done a little touch up on
{
"textRaw": "assert(value[, message]), assert.ok(value[, message])",
"type": "method",
"name": "ok",
"meta": {
"stability": 0,
"added": "v0.10.0",
"deprecated": "v4.0.0"
},
"desc": "<p>Tests if <code>value</code> is truthy. It is equivalent to\n<code>assert.equal(!!value, true, message)</code>.\n\n</p>\n<p>If <code>value</code> is not truthy, an <code>AssertionError</code> is thrown with a <code>message</code>\nproperty set equal to the value of the <code>message</code> parameter. If the <code>message</code>\nparameter is <code>undefined</code>, a default error message is assigned.\n\n</p>\n<pre><code class=\"js\">const assert = require('assert');\n\nassert(true); // OK\nassert(1); // OK\nassert(false);\n // throws "AssertionError: false == true"\nassert(0);\n // throws "AssertionError: 0 == true"\nassert(false, 'it\\'s false');\n // throws "AssertionError: it's false"\n\nassert.ok(true); // OK\nassert.ok(1); // OK\nassert.ok(false);\n // throws "AssertionError: false == true"\nassert.ok(0);\n // throws "AssertionError: 0 == true"\nassert.ok(false, 'it\\'s false');\n // throws "AssertionError: it's false"</code></pre>\n",
"signatures": [
{
"params": [
{
"name": "value"
},
{
"name": "message])"
},
{
"name": "assert.ok(value"
},
{
"name": "message",
"optional": true
}
]
}
]
}Here is the CSS: .api_metadata {
font-size: .75em;
margin-bottom: 1em;
}
.api_metadata span {
margin-right: 1em;
}
.api_metadata span:last-child {
margin-right: 0px;
} |
tflanagan
force-pushed
the
doc-parse-since-ver
branch
3 times, most recently
from
ae6c941
to
6d1a70f
Compare
|
That's fine, in terms of adding the actual data to the docs, I imagine something like one commit per doc file is what is desired? Edit: I would do that in a different PR |
|
Yeah, I'd think so, anything else becomes too difficult to rebase if things change while the PR is being reviewed. |
tflanagan
changed the title
|
/poke |
|
/cc @nodejs/documentation |
|
generally LGTM |
|
@tflanagan Could you rebase this again? |
estliberitas
force-pushed
the
master
branch
2 times, most recently
from
7da4fd4
to
c7066fb
Compare
|
ping @tflanagan again – still interested in this? if not, would you mind if someone else took this PR up again? |
|
@addaleax ... at this point I'd say if you'd like to pick this up go for it. It's been stalled for a while. |
|
Continuing this in #6495. |
This commit introduces the Documentation YAML metadata concept to the documentation. - Parses added or Added for HTML - Parses all data for JSON Ref: #3867 Ref: #3713 Ref: #6470 PR-URL: #6495 Reviewed-By: Robert Jefe Lindstaedt <[email protected]> Reviewed-By: James M Snell <[email protected]> Reviewed-By: Jeremiah Senkpiel <[email protected]>
|
Pleased to announce that, after almost half a year, this has landed with some minor tweaking in 015f4fd! 🎉 |
This commit introduces the Documentation YAML metadata concept to the documentation. - Parses added or Added for HTML - Parses all data for JSON Ref: #3867 Ref: #3713 Ref: #6470 PR-URL: #6495 Reviewed-By: Robert Jefe Lindstaedt <[email protected]> Reviewed-By: James M Snell <[email protected]> Reviewed-By: Jeremiah Senkpiel <[email protected]>
This commit introduces the Documentation YAML metadata concept to the documentation. - Parses added or Added for HTML - Parses all data for JSON Ref: nodejs#3867 Ref: nodejs#3713 Ref: nodejs#6470 PR-URL: nodejs#6495 Reviewed-By: Robert Jefe Lindstaedt <[email protected]> Reviewed-By: James M Snell <[email protected]> Reviewed-By: Jeremiah Senkpiel <[email protected]>
This commit introduces the Documentation YAML metadata concept to the documentation. - Parses added or Added for HTML - Parses all data for JSON Ref: #3867 Ref: #3713 Ref: #6470 PR-URL: #6495 Reviewed-By: Robert Jefe Lindstaedt <[email protected]> Reviewed-By: James M Snell <[email protected]> Reviewed-By: Jeremiah Senkpiel <[email protected]>
This commit introduces the Documentation YAML metadata concept to the documentation. - Parses added or Added for HTML - Parses all data for JSON Ref: #3867 Ref: #3713 Ref: #6470 PR-URL: #6495 Reviewed-By: Robert Jefe Lindstaedt <[email protected]> Reviewed-By: James M Snell <[email protected]> Reviewed-By: Jeremiah Senkpiel <[email protected]>
This commit introduces the Documentation YAML metadata concept to the documentation. - Parses added or Added for HTML - Parses all data for JSON Ref: #3867 Ref: #3713 Ref: #6470 PR-URL: #6495 Reviewed-By: Robert Jefe Lindstaedt <[email protected]> Reviewed-By: James M Snell <[email protected]> Reviewed-By: Jeremiah Senkpiel <[email protected]>
This commit introduces the Documentation YAML metadata concept to the
documentation.
This is in prelude to #3713.
Markup would look like this: