Skip to content

Commit d10362f

Browse files
stephenplusplusstephenplusplus
authored
generate google-cloud gapic docs correctly (#2485)
1 parent 5883af7 commit d10362f

2 files changed

Lines changed: 147 additions & 85 deletions

File tree

‎scripts/docs/builder.js‎

Lines changed: 74 additions & 30 deletions
Original file line numberDiff line numberDiff line change
@@ -98,7 +98,7 @@ Builder.prototype.build = function() {
9898
});
9999

100100
var gapicVersions = docs.reduce((grouped, doc) => {
101-
var gapicVersion = doc.id.match(/[/_](v[^\/]*)/);
101+
var gapicVersion = doc.id.match(/[/_](v\d[^\/]*)/);
102102

103103
if (gapicVersion) {
104104
gapicVersion = gapicVersion[1];
@@ -200,38 +200,57 @@ Builder.prototype.build = function() {
200200
methods: [],
201201
path: `${gapicVersion}/index.json`,
202202
description: `
203-
<h1>{{docs.services[0].title}} API Contents</h1>
204-
205-
<table class="table">
206-
<thead>
207-
<tr>
208-
<th>Class</th>
209-
<th>Description</th>
210-
</tr>
211-
</thead>
212-
<tbody>
213-
<tr
214-
ng-repeat="client in docs.services[docs.services.length - 1].nav"
215-
ng-if="client.title.includes('Client')">
216-
<td>
217-
<a ui-sref="docs.service({
218-
serviceId: client.type
219-
})">{{client.title}}</a>
220-
</td>
221-
<td>
222-
Create a {{client.title}} to interact with the {{docs.services[0].title}} API.
223-
</td>
224-
</tr>
225-
${dataTypesMarkup}
226-
</tbody>
227-
</table>
203+
<div ng-if="docs.services[0].title === 'Google Cloud'">
204+
To explore this API, use the links in the navigation bar.
205+
</div>
206+
<div ng-if="docs.services[0].title !== 'Google Cloud'">
207+
<h1>{{docs.services[0].title}} API Contents</h1>
208+
209+
<table class="table">
210+
<thead>
211+
<tr>
212+
<th>Class</th>
213+
<th>Description</th>
214+
</tr>
215+
</thead>
216+
<tbody>
217+
<tr
218+
ng-repeat="client in docs.services[docs.services.length - 1].nav"
219+
ng-if="client.title.includes('Client')">
220+
<td>
221+
<a ui-sref="docs.service({
222+
serviceId: client.type
223+
})">{{client.title}}</a>
224+
</td>
225+
<td>
226+
Create a {{client.title}} to interact with the {{docs.services[0].title}} API.
227+
</td>
228+
</tr>
229+
${dataTypesMarkup}
230+
</tbody>
231+
</table>
232+
</div>
228233
`
229234
});
230235
}
231236

232237
var types = parser.createTypesDictionary(docs);
233238
var toc = parser.createToc(types);
234239

240+
var generatedType;
241+
toc.services = toc.services.filter(service => {
242+
if (/^v\d/.test(service.title)) {
243+
if (!service.nav) {
244+
generatedType = service.type;
245+
return false;
246+
} else {
247+
service.type = generatedType;
248+
}
249+
}
250+
251+
return service;
252+
});
253+
235254
toc.tagName = this.getTagName();
236255
this.write(config.TYPES_DICT, types);
237256
this.write(config.TOC, toc);
@@ -424,16 +443,26 @@ Bundler.prototype.add = function(builder) {
424443

425444
mkdir('-p', outputFolder);
426445

427-
globby.sync(path.resolve(builder.dir, '*.json'), {
446+
globby.sync(path.resolve(builder.dir, '**/*.json'), {
428447
ignore: [config.TYPES_DICT, config.TOC].map(function(file) {
429448
return path.resolve(builder.dir, file);
430449
})
431450
}).forEach(function(file) {
432451
var json = require(file);
433-
var service = json.parent || json.id;
434-
var outputFile = path.join(builder.name, path.basename(file));
452+
var outputFile;
453+
454+
var gapicVersion = file.match(/\/v\d[^/]*/) && file.match(/\/v\d[^/]*/)[0];
455+
456+
if (gapicVersion) {
457+
var versionOutputFolder = path.join(outputFolder, gapicVersion);
458+
mkdir('-p', versionOutputFolder);
459+
outputFile = path.join(builder.name, gapicVersion, path.basename(file));
460+
} else {
461+
var service = json.parent || json.id;
462+
json.overview = parser.createOverview(service, true);
463+
outputFile = path.join(builder.name, path.basename(file));
464+
}
435465

436-
json.overview = parser.createOverview(service, true);
437466
self.builder.write(outputFile, json);
438467
});
439468
};
@@ -478,6 +507,21 @@ Bundler.prototype.bundle = function() {
478507
var types = baseTypes.concat(flatten(depTypes));
479508
var toc = parser.createToc(types, true);
480509

510+
toc.services = toc.services.filter(service => {
511+
if (service.nav) {
512+
service.nav = service.nav.filter(innerService => {
513+
// Empty generated version nav items.
514+
if (/^v\d/.test(innerService.title) && !innerService.nav) {
515+
return false;
516+
}
517+
518+
return true;
519+
});
520+
}
521+
522+
return service;
523+
});
524+
481525
toc.tagName = this.builder.getTagName();
482526
this.builder.write(config.TYPES_DICT, types);
483527
this.builder.write(config.TOC, toc);

‎scripts/docs/parser.js‎

Lines changed: 73 additions & 55 deletions
Original file line numberDiff line numberDiff line change
@@ -388,13 +388,14 @@ function parseFile(fileName, contents, umbrellaMode) {
388388

389389
function createTypesDictionary(docs) {
390390
var types = [];
391-
var gapicVersions = [];
391+
var gapics = {};
392392

393393
docs.forEach(function(service) {
394394
var isGapic = /_client$/.test(service.id);
395395

396396
var titleParts = [];
397397
var id = service.id;
398+
398399
var contents = service.path;
399400

400401
if (id === config.UMBRELLA_PACKAGE) {
@@ -415,17 +416,25 @@ function createTypesDictionary(docs) {
415416
}
416417
});
417418

418-
if (!arrayIncludes(gapicVersions, gapicVersion)) {
419-
gapicVersions.push(gapicVersion);
420-
}
421-
422419
titleParts = [gapicVersion];
423420

424421
var nestedTitle = [].slice.call(gapicPath, versionIndex + 1);
425422

426423
if (nestedTitle.length > 0) {
427424
titleParts.push(upperFirst(camel(nestedTitle.join('/'))));
428425
}
426+
427+
var gapicPathWithVersion = [].slice.call(gapicPath)
428+
.slice(0, versionIndex + 1).join('/');
429+
430+
if (!gapics[gapicPathWithVersion]) {
431+
gapics[gapicPathWithVersion] = {
432+
id: gapicPathWithVersion,
433+
title: [
434+
gapicVersion
435+
]
436+
};
437+
}
429438
}
430439

431440
if (service.parent) {
@@ -443,25 +452,22 @@ function createTypesDictionary(docs) {
443452
});
444453
});
445454

446-
gapicVersions.forEach(gapicVersion => {
455+
for (var gapic in gapics) {
447456
types.push({
448-
id: gapicVersion,
449-
title: [gapicVersion],
450-
contents: `${gapicVersion}/index.json`
457+
id: gapics[gapic].id,
458+
title: gapics[gapic].title,
459+
contents: `${gapics[gapic].title}/index.json`
451460
});
452-
});
461+
}
453462

454463
return types;
455464
}
456465

457466
function createToc(types, collapse) {
458-
var PATH_VERSION_REGEX = /\/(v[^/]*)/;
459-
460467
var toc = extend(true, {}, baseToc);
461468

462469
var generatedTypes = types.filter(type => / v\d/.test(type.title.join(' ')));
463470
var protos = types.filter(type => stringIncludes(type.id, '/doc/'));
464-
var protosGroupedByVersion = {};
465471

466472
var services = types
467473
.filter(type => !arrayIncludes(generatedTypes, type))
@@ -484,61 +490,73 @@ function createToc(types, collapse) {
484490
return a.type < b.type ? -1 : a.type > b.type ? 1 : 0;
485491
});
486492

487-
if (protos.length > 0) {
488-
protos.forEach(function(proto) {
489-
var version = proto.id.match(PATH_VERSION_REGEX)[1];
490-
protosGroupedByVersion[version] = protosGroupedByVersion[version] || [];
491-
protosGroupedByVersion[version].push(proto);
492-
});
493-
}
494-
495493
if (generatedTypes.length > 0) {
496494
// Push the generated types to the bottom of the navigation.
497-
var generatedTypesByVersion = {};
495+
var generatedTypesByModuleByVersion = {};
498496

499497
generatedTypes.forEach(function(generatedType) {
498+
var module = generatedType.title[0];
499+
var moduleObject = generatedTypesByModuleByVersion[module] =
500+
generatedTypesByModuleByVersion[module] || {};
501+
500502
var version = generatedType.title[1];
501-
generatedTypesByVersion[version] = generatedTypesByVersion[version] || [];
502-
generatedTypesByVersion[version].push(generatedType);
503+
moduleObject[version] = moduleObject[version] || [];
504+
moduleObject[version].push(generatedType);
503505
});
504506

505-
for (var version in generatedTypesByVersion) {
506-
var generatedTypesGrouped = generatedTypesByVersion[version]
507-
.sort(function(a, b) {
508-
if (a.title.length < b.title.length) { // e.g. ['Spanner', 'v1']
509-
return -1;
510-
}
507+
for (var module in generatedTypesByModuleByVersion) {
508+
var versions = generatedTypesByModuleByVersion[module];
511509

512-
if (b.title.length < a.title.length) {
513-
return 1;
514-
}
510+
for (var version in versions) {
511+
/*jshint loopfunc:true*/
512+
var matchingService = services.filter(service => {
513+
return service.title.toLowerCase() === module.toLowerCase();
514+
})[0];
515515

516-
var titleA = a.title[a.title.length - 1];
517-
var titleB = b.title[b.title.length - 1];
516+
var generatedTypesGrouped = versions[version]
517+
.sort(function(a, b) {
518+
if (a.title.length < b.title.length) { // e.g. ['Spanner', 'v1']
519+
return -1;
520+
}
518521

519-
return titleA < titleB ? -1 : titleA > titleB ? 1 : 0;
520-
});
522+
if (b.title.length < a.title.length) {
523+
return 1;
524+
}
521525

522-
/*jshint loopfunc:true*/
523-
services = services.filter(service => service.type !== version);
524-
525-
var serviceObject = {
526-
title: version,
527-
type: version,
528-
nav: generatedTypesGrouped.map(function(generatedType) {
529-
return {
530-
title: generatedType.title[generatedType.title.length - 1],
531-
type: generatedType.id
532-
};
533-
})
534-
};
526+
var titleA = a.title[a.title.length - 1];
527+
var titleB = b.title[b.title.length - 1];
535528

536-
serviceObject.nav.push({
537-
title: 'Data Types',
538-
type: generatedTypes[0].id.replace(/\/\w+_client$/, '/data_types')
539-
});
529+
return titleA < titleB ? -1 : titleA > titleB ? 1 : 0;
530+
});
540531

541-
services.push(serviceObject);
532+
services = services.filter(service => {
533+
return service.type !== version;
534+
});
535+
536+
var serviceObject = {
537+
title: version,
538+
type: version,
539+
nav: generatedTypesGrouped.map(function(generatedType) {
540+
return {
541+
title: generatedType.title[generatedType.title.length - 1],
542+
type: generatedType.id
543+
};
544+
})
545+
};
546+
547+
serviceObject.nav.push({
548+
title: 'Data Types',
549+
type: generatedTypesGrouped[0].id
550+
.replace(/\/\w+_client$/, '/data_types')
551+
});
552+
553+
if (collapse) { // Umbrella mode
554+
serviceObject.type = `${module.toLowerCase()}/${serviceObject.type}`;
555+
matchingService.nav = [serviceObject];
556+
} else {
557+
services.push(serviceObject);
558+
}
559+
}
542560
}
543561
}
544562

0 commit comments

Comments
 (0)