Skip to content

build(aio) + docs: miscellaneous updates to the doc-gen #24000

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Closed
petebacondarwin wants to merge 21 commits into from
Closed

build(aio) + docs: miscellaneous updates to the doc-gen #24000

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
21 commits
Select commit Hold shift + click to select a range
c5f1798
build(aio): don't render `@Annotation` tags
petebacondarwin May 16, 2018
14fcd3b
build(aio): do not try to auto-link to internal API items
petebacondarwin May 16, 2018
9e1050c
build(aio): don't constrain `checkContentRules` to run before another…
petebacondarwin May 16, 2018
dfab9ab
build(aio): add content rule to prevent usageNotes in non-export API …
petebacondarwin May 16, 2018
c364efc
build(aio): update to latest dgeni-packages@0.26.2
petebacondarwin May 16, 2018
1f9e43a
build(aio): do not allow `@usageNotes` on properties
petebacondarwin May 18, 2018
981ee7c
build(aio): refactor the decorator doc processing
petebacondarwin May 18, 2018
b0aa39b
docs(aio): remove unused guide doc
petebacondarwin May 18, 2018
be016e7
build(aio): improve automatic linking of code items
petebacondarwin May 18, 2018
d552300
docs: remove unnecessary `@linkDocs` tags
petebacondarwin May 18, 2018
54b7a39
build(aio): remove unused `@linkDocs` alias for `@link` jsdoc tag
petebacondarwin May 18, 2018
5fe50e6
build(aio): rearrange decorator API doc template
petebacondarwin May 18, 2018
44e2f93
build(aio): map H3 headings into H4 headings for certain templates
petebacondarwin May 18, 2018
54b0103
docs: fix invalid headings
petebacondarwin May 18, 2018
e682cd2
build(aio): rearrange processors to ensure we catch all content errors
petebacondarwin May 18, 2018
686c6d6
build(aio): remove invalid H3 usage notes heading
petebacondarwin May 23, 2018
bf87296
build(aio): fix broken doc-gen unit test
petebacondarwin May 23, 2018
3c24fd1
fix(aio): tidy up API doc styles
petebacondarwin May 23, 2018
d927c14
build(aio): fix decorator doc "inherited from" heading
petebacondarwin May 23, 2018
8ea4779
build(aio): compute breadcrums for all API doc types
petebacondarwin May 23, 2018
14acfc2
build(aio): add github links to API doc members
petebacondarwin May 23, 2018
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
175 changes: 0 additions & 175 deletions aio/content/guide/api-page-class.md
View file
Open in desktop

This file was deleted.

2 changes: 1 addition & 1 deletion aio/package.json
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -112,7 +112,7 @@
"cross-spawn": "^5.1.0",
"css-selector-parser": "^1.3.0",
"dgeni": "^0.4.7",
"dgeni-packages": "^0.26.1",
"dgeni-packages": "^0.26.2",
"entities": "^1.1.1",
"eslint": "^3.19.0",
"eslint-plugin-jasmine": "^2.2.0",
Expand Down
79 changes: 0 additions & 79 deletions aio/src/styles/1-layouts/_api-page.scss
View file
Open in desktop

This file was deleted.

41 changes: 41 additions & 0 deletions aio/src/styles/1-layouts/_api-pages.scss
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,41 @@
.api-body {

max-width: 1200px;

table {

th {
text-transform: none;
font-size: 16px;
font-weight: bold;
}

tr {
border-bottom: 1px solid $lightgray;
}

td {
vertical-align: middle;
}

hr {
margin: 16px 0;
}

tr:last-child {
border-bottom: none;
}

&.item-table {
td {
padding: 32px;
}
}

&.list-table {
td {
padding: 16px 24px;
}
}
}
}
2 changes: 1 addition & 1 deletion aio/src/styles/1-layouts/_layouts-dir.scss
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -2,7 +2,7 @@
LAYOUT STYLES
============================== */

@import 'api-page';
@import 'api-pages';
@import 'content-layout';
@import 'doc-viewer';
@import 'footer';
Expand Down
1 change: 1 addition & 0 deletions aio/src/styles/2-modules/_api-list.scss
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -280,6 +280,7 @@ p {
.code-anchor {
cursor: pointer;
text-decoration: none;
font-size: inherit;

&:hover {
text-decoration: underline;
Expand Down
28 changes: 22 additions & 6 deletions aio/src/styles/2-modules/_api-pages.scss
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,4 +1,4 @@
.page-actions {
.github-links {
float: right;
.material-icons {
border-radius: 4px;
Expand Down Expand Up @@ -30,10 +30,30 @@
}
}

.method-table {
.method-table, .option-table {
th {
display: flex;
align-items: center;

h3 {
flex: 1;
}

.github-links {
a {
color: $mediumgray;
.material-icons:hover {
background: none;
color: $blue;
}
}
}
}

h3 {
margin: 6px 0;
font-weight: bold;
clear: left;
}

h4 {
Expand Down Expand Up @@ -87,10 +107,6 @@
}
}

.api-section aio-code {
background-color: rgba(241, 241, 241, 0.2);
}

.from-constructor, .read-only-property {
font-style: italic;
color: $blue;
Expand Down
67 changes: 63 additions & 4 deletions aio/tools/transforms/angular-api-package/index.js
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -42,12 +42,19 @@ module.exports = new Package('angular-api', [basePackage, typeScriptPackage])
return EXPORT_DOC_TYPES.concat(['decorator', 'directive', 'pipe', 'module']);
})

/**
* These are the doc types that are contained within other docs
*/
.factory(function API_CONTAINED_DOC_TYPES() {
return ['member', 'function-overload', 'get-accessor-info', 'set-accessor-info', 'parameter'];
})

/**
* These are the doc types that are API docs, including ones that will be merged into container docs,
* such as members and overloads.
*/
.factory(function API_DOC_TYPES(API_DOC_TYPES_TO_RENDER) {
return API_DOC_TYPES_TO_RENDER.concat(['member', 'function-overload']);
.factory(function API_DOC_TYPES(API_DOC_TYPES_TO_RENDER, API_CONTAINED_DOC_TYPES) {
return API_DOC_TYPES_TO_RENDER.concat(API_CONTAINED_DOC_TYPES);
})

// Where do we get the source files?
Expand Down Expand Up @@ -112,8 +119,8 @@ module.exports = new Package('angular-api', [basePackage, typeScriptPackage])
parseTagsProcessor.tagDefinitions.concat(getInjectables(requireFolder(__dirname, './tag-defs')));
})

.config(function(computeStability, splitDescription, addNotYetDocumentedProperty, EXPORT_DOC_TYPES, API_DOC_TYPES) {
computeStability.docTypes = EXPORT_DOC_TYPES;
.config(function(computeStability, splitDescription, addNotYetDocumentedProperty, API_DOC_TYPES_TO_RENDER, API_DOC_TYPES) {
computeStability.docTypes = API_DOC_TYPES_TO_RENDER;
// Only split the description on the API docs
splitDescription.docTypes = API_DOC_TYPES;
addNotYetDocumentedProperty.docTypes = API_DOC_TYPES;
Expand Down Expand Up @@ -155,6 +162,16 @@ module.exports = new Package('angular-api', [basePackage, typeScriptPackage])
});
})

.config(function(filterContainedDocs, API_CONTAINED_DOC_TYPES) {
filterContainedDocs.docTypes = API_CONTAINED_DOC_TYPES;
})

.config(function(checkContentRules, API_DOC_TYPES, API_CONTAINED_DOC_TYPES) {
addMinLengthRules(checkContentRules);
addHeadingRules(checkContentRules, API_DOC_TYPES);
addAllowedPropertiesRules(checkContentRules, API_CONTAINED_DOC_TYPES);
})

.config(function(computePathsProcessor, EXPORT_DOC_TYPES, generateApiListDoc) {

const API_SEGMENT = 'api';
Expand Down Expand Up @@ -188,3 +205,45 @@ module.exports = new Package('angular-api', [basePackage, typeScriptPackage])
autoLinkCode.docTypes = API_DOC_TYPES;
autoLinkCode.codeElements = ['code', 'code-example', 'code-pane'];
});


function addMinLengthRules(checkContentRules) {
const createMinLengthRule = require('./content-rules/minLength');
const paramRuleSet = checkContentRules.docTypeRules['parameter'] = checkContentRules.docTypeRules['parameter'] || {};
const paramRules = paramRuleSet['name'] = paramRuleSet['name'] || [];
paramRules.push(createMinLengthRule());
}

function addHeadingRules(checkContentRules, API_DOC_TYPES) {
const createNoMarkdownHeadingsRule = require('./content-rules/noMarkdownHeadings');
const noMarkdownHeadings = createNoMarkdownHeadingsRule();
const allowOnlyLevel3Headings = createNoMarkdownHeadingsRule(1, 2, '4,');

API_DOC_TYPES.forEach(docType => {
let rules;
const ruleSet = checkContentRules.docTypeRules[docType] = checkContentRules.docTypeRules[docType] || {};

rules = ruleSet['description'] = ruleSet['description'] || [];
rules.push(noMarkdownHeadings);

rules = ruleSet['shortDescription'] = ruleSet['shortDescription'] || [];
rules.push(noMarkdownHeadings);

rules = ruleSet['usageNotes'] = ruleSet['usageNotes'] || [];
rules.push(allowOnlyLevel3Headings);
});
}

function addAllowedPropertiesRules(checkContentRules, API_CONTAINED_DOC_TYPES) {
API_CONTAINED_DOC_TYPES.forEach(docType => {
const ruleSet = checkContentRules.docTypeRules[docType] = checkContentRules.docTypeRules[docType] || {};

const rules = ruleSet['usageNotes'] = ruleSet['usageNotes'] || [];
rules.push((doc, prop, value) => value && !isMethod(doc) &&

@gkalpak gkalpak May 22, 2018

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Does this rule mean that usageNotes are only allowed in methods?

@petebacondarwin petebacondarwin May 23, 2018

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Not quite. This rule only runs on docs that are of the types given in API_CONTAINED_DOC_TYPES. It just turns out that all methods and properties are of the same docType (i.e. member) so we have to have this additional check here.
So since the rule doesn't run on other docTypes (e.g. class or function) they are not constrained by it.

@gkalpak gkalpak May 23, 2018

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

So, this means that usageNotes are not allowed in members, except for methods (where they are allowed)?

@petebacondarwin petebacondarwin May 23, 2018

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

right and also function-overload, get-accessor-info, set-accessor-info and parameter docs

`Invalid property: "${prop}" is not allowed on "${doc.docType}" docs.`);
});
}

function isMethod(doc) {
return doc.hasOwnProperty('parameters') && !doc.isGetAccessor && !doc.isSetAccessor;

@gkalpak gkalpak May 22, 2018

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Do constructors count?

@petebacondarwin petebacondarwin May 23, 2018 •
edited
Loading

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I think so yes, constructors are a kind of method according to this definition.

}
13 changes: 6 additions & 7 deletions aio/tools/transforms/angular-api-package/processors/computeApiBreadCrumbs.js
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,16 +1,15 @@
module.exports = function computeApiBreadCrumbs(EXPORT_DOC_TYPES) {
module.exports = function computeApiBreadCrumbs(API_DOC_TYPES_TO_RENDER) {
return {
$runAfter: ['paths-computed'],
$runBefore: ['rendering-docs'],
$process(docs) {
// Compute the breadcrumb for each doc by processing its containers
docs.forEach(doc => {
if (EXPORT_DOC_TYPES.indexOf(doc.docType) !== -1) {
doc.breadCrumbs = [
{ text: 'API', path: '/api' },
{ text: '@angular/' + doc.moduleDoc.id, path: doc.moduleDoc.path },
{ text: doc.name, path: doc.path }
];
if (API_DOC_TYPES_TO_RENDER.indexOf(doc.docType) !== -1) {
doc.breadCrumbs = [];
doc.breadCrumbs.push({ text: 'API', path: '/api' });
if (doc.moduleDoc) doc.breadCrumbs.push({ text: '@angular/' + doc.moduleDoc.id, path: doc.moduleDoc.path });

@gkalpak gkalpak May 24, 2018

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

  1. There is no test for this conditional 😱
  2. Under what circumstances can a doc have no corresponding moduleDoc? Do you have an example?

@petebacondarwin petebacondarwin May 25, 2018

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

when it is a module? I'll add a test

doc.breadCrumbs.push({ text: doc.name, path: doc.path });
}
});
}
Expand Down
11 changes: 8 additions & 3 deletions aio/tools/transforms/angular-api-package/processors/computeApiBreadCrumbs.spec.js
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -13,14 +13,15 @@ describe('angular-api-package: computeApiBreadCrumbs processor', () => {
expect(processor.$runBefore).toEqual(['rendering-docs']);
});

it('should attach a breadCrumbs property to each of the EXPORT_DOC_TYPES docs', () => {
const EXPORT_DOC_TYPES = ['class', 'interface'];
const processor = processorFactory(EXPORT_DOC_TYPES);
it('should attach a breadCrumbs property to each of the API_DOC_TYPES_TO_RENDER docs', () => {
const API_DOC_TYPES_TO_RENDER = ['class', 'interface', 'module'];
const processor = processorFactory(API_DOC_TYPES_TO_RENDER);

const docs = [
{ docType: 'class', name: 'ClassA', path: 'module-1/class-a', moduleDoc: { id: 'moduleOne', path: 'module-1' } },
{ docType: 'interface', name: 'InterfaceB', path: 'module-2/interface-b', moduleDoc: { id: 'moduleTwo', path: 'module-2' } },
{ docType: 'guide', name: 'Guide One', path: 'guide/guide-1' },
{ docType: 'module', name: 'testing', id: 'http/testing', path: 'http/testing' },
];
processor.$process(docs);

Expand All @@ -35,5 +36,9 @@ describe('angular-api-package: computeApiBreadCrumbs processor', () => {
{ text: 'InterfaceB', path: 'module-2/interface-b' },
]);
expect(docs[2].breadCrumbs).toBeUndefined();
expect(docs[3].breadCrumbs).toEqual([
{ text: 'API', path: '/api' },
{ text: 'testing', path: 'http/testing' },
]);
});
});
2 changes: 1 addition & 1 deletion aio/tools/transforms/angular-api-package/processors/filterContainedDocs.js
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -5,7 +5,7 @@
module.exports = function filterContainedDocs() {
return {
docTypes: ['member', 'function-overload', 'get-accessor-info', 'set-accessor-info', 'parameter'],
$runAfter: ['extra-docs-added'],
$runAfter: ['extra-docs-added', 'checkContentRules'],
$runBefore: ['computing-paths'],
$process: function(docs) {
var docTypes = this.docTypes;
Expand Down
2 changes: 1 addition & 1 deletion aio/tools/transforms/angular-api-package/processors/filterPrivateDocs.js
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
module.exports = function filterPrivateDocs() {
return {
$runAfter: ['extra-docs-added'],
$runAfter: ['extra-docs-added', 'checkContentRules'],
$runBefore: ['computing-paths'],
$process: function(docs) {
return docs.filter(function(doc) { return doc.privateExport !== true; });
Expand Down
2 changes: 1 addition & 1 deletion aio/tools/transforms/angular-api-package/processors/filterPrivateDocs.spec.js
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -18,7 +18,7 @@ describe('filterPrivateDocs processor', () => {

it('should run after the correct processor', () => {
const processor = processorFactory();
expect(processor.$runAfter).toEqual(['extra-docs-added']);
expect(processor.$runAfter).toEqual(['extra-docs-added', 'checkContentRules']);
});

it('should remove docs that are marked as private exports', () => {
Expand Down
Loading