FazBrowse GitHub Viewer | Trending |
URL:
| Home
Tools: [Download Repo ZIP]   [Original HTTPS Page]

tools: Include links to source code in documentation · nodejs/node@50100f3 · GitHub

/ node Public

Commit 50100f3

Browse files
rubys
authored and
targos
committed
tools: Include links to source code in documentation
Parse source code using acorn; extracting exports. When producing documentation, match exports to headers. When a match is found, add a [src] link. This first commit handles simple exported classes and functions, and does so without requiring any changes to the source code or markdown. Subsequent commits will attempt to match more headers, and some of these changes are likely to require changes to the source code and/or markdown. PR-URL: #22405 Reviewed-By: James M Snell <jasnell@gmail.com> Reviewed-By: Refael Ackermann <refack@gmail.com> Reviewed-By: Vse Mozhet Byt <vsemozhetbyt@gmail.com>
1 parent d3bb741 commit 50100f3

13 files changed

Lines changed: 252 additions & 4 deletions

File tree

‎Makefile‎

Lines changed: 6 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -645,10 +645,15 @@ out/doc/api/assets/%: doc/api_assets/% out/doc/api/assets
645645
run-npm-ci = $(PWD)/$(NPM) ci
646646

647647
gen-api = tools/doc/generate.js --node-version=$(FULLVERSION) \
648+
--apilinks=out/apilinks.json \
648649
--analytics=$(DOCS_ANALYTICS) $< --output-directory=out/doc/api
650+
gen-apilink = tools/doc/apilinks.js $(wildcard lib/*.js) > $@
651+
652+
out/apilinks.json: $(wildcard lib/*.js) tools/doc/apilinks.js
653+
$(call available-node, $(gen-apilink))
649654

650655
out/doc/api/%.json out/doc/api/%.html: doc/api/%.md tools/doc/generate.js \
651-
tools/doc/html.js tools/doc/json.js
656+
tools/doc/html.js tools/doc/json.js | out/apilinks.json
652657
$(call available-node, $(gen-api))
653658

654659
out/doc/api/all.html: $(apidocs_html) tools/doc/allhtml.js

‎doc/api_assets/style.css‎

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -283,6 +283,11 @@ h2, h3, h4, h5 {
283283
padding-right: 40px;
284284
}
285285

286+
.srclink {
287+
float: right;
288+
font-size: smaller;
289+
}
290+
286291
h1 span, h2 span, h3 span, h4 span {
287292
position: absolute;
288293
display: block;

‎test/doctool/test-apilinks.js‎

Lines changed: 39 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,39 @@
1+
'use strict';
2+
3+
require('../common');
4+
const fixtures = require('../common/fixtures');
5+
const fs = require('fs');
6+
const assert = require('assert');
7+
const path = require('path');
8+
const { execFileSync } = require('child_process');
9+
10+
const script = path.join(__dirname, '..', '..', 'tools', 'doc', 'apilinks.js');
11+
12+
const apilinks = fixtures.path('apilinks');
13+
fs.readdirSync(apilinks).forEach((fixture) => {
14+
if (!fixture.endsWith('.js')) return;
15+
const file = path.join(apilinks, fixture);
16+
17+
const expectedContent = fs.readFileSync(file + 'on', 'utf8');
18+
19+
const output = execFileSync(
20+
process.execPath,
21+
[script, file],
22+
{ encoding: 'utf-8' }
23+
);
24+
25+
const expectedLinks = JSON.parse(expectedContent);
26+
const actualLinks = JSON.parse(output);
27+
28+
for (const [k, v] of Object.entries(expectedLinks)) {
29+
assert.ok(k in actualLinks, `link not found: ${k}`);
30+
assert.ok(actualLinks[k].endsWith('/' + v),
31+
`link ${actualLinks[k]} expected to end with ${v}`);
32+
delete actualLinks[k];
33+
}
34+
35+
assert.strictEqual(
36+
Object.keys(actualLinks).length, 0,
37+
`unexpected links returned ${JSON.stringify(actualLinks)}`
38+
);
39+
});

‎test/doctool/test-doctool-html.js‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -28,7 +28,7 @@ function toHTML({ input, filename, nodeVersion, analytics }, cb) {
2828
.use(html.firstHeader)
2929
.use(html.preprocessText)
3030
.use(html.preprocessElements, { filename })
31-
.use(html.buildToc, { filename })
31+
.use(html.buildToc, { filename, apilinks: {} })
3232
.use(remark2rehype, { allowDangerousHTML: true })
3333
.use(raw)
3434
.use(htmlStringify)

‎test/fixtures/apilinks/buffer.js‎

Lines changed: 12 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,12 @@
1+
'use strict';
2+
3+
// Buffer instance methods are exported as 'buf'.
4+
5+
function Buffer() {
6+
}
7+
8+
Buffer.prototype.instanceMethod = function() {}
9+
10+
module.exports = {
11+
Buffer
12+
};

‎test/fixtures/apilinks/buffer.json‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,4 @@
1+
{
2+
"buffer.Buffer": "buffer.js#L5",
3+
"buf.instanceMethod": "buffer.js#L8"
4+
}

‎test/fixtures/apilinks/mod.js‎

Lines changed: 11 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,11 @@
1+
'use strict';
2+
3+
// A module may export one or more methods.
4+
5+
function foo() {
6+
}
7+
8+
9+
module.exports = {
10+
foo
11+
};

‎test/fixtures/apilinks/mod.json‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,3 @@
1+
{
2+
"mod.foo": "mod.js#L5"
3+
}

‎test/fixtures/apilinks/prototype.js‎

Lines changed: 13 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,13 @@
1+
'use strict';
2+
3+
// An exported class using classic prototype syntax.
4+
5+
function Class() {
6+
}
7+
8+
Class.classMethod = function() {}
9+
Class.prototype.instanceMethod = function() {}
10+
11+
module.exports = {
12+
Class
13+
};

‎test/fixtures/apilinks/prototype.json‎

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,5 @@
1+
{
2+
"prototype.Class": "prototype.js#L5",
3+
"Class.classMethod": "prototype.js#L8",
4+
"class.instanceMethod": "prototype.js#L9"
5+
}

0 commit comments

Comments
 (0)
Back | FazBrowse Home | New Git URL