cargdev/angular
1
0
Fork 0
Code Issues 14 Pull Requests Actions Packages Projects Releases Wiki Activity

build(docs-infra): expose deprecated status on items more clearly (#25750)

Browse Source 
PR Close #25750
This commit is contained in:
Pete Bacon Darwin
2018-09-17 17:37:18 +01:00
committed by Kara Erickson
parent cea2e0477c
commit 026b60cd70
22 changed files with 321 additions and 93 deletions
Download Patch File Download Diff File Expand all files Collapse all files

13
aio/tools/transforms/angular-api-package/processors/processPackages.js vendored
View File

@ -2,8 +2,8 @@ const { dirname } = require('canonical-path');
module.exports = function processPackages() {
return {
$runAfter: ['extractDecoratedClassesProcessor'],
$runBefore: ['computing-ids'],
$runAfter: ['extractDecoratedClassesProcessor', 'computeStability'],
$runBefore: ['computing-ids', 'generateKeywordsProcessor'],
$process(docs) {
const packageContentFiles = {};
const packageMap = {};
@ -34,6 +34,9 @@ module.exports = function processPackages() {
doc.directives = doc.exports.filter(doc => doc.docType === 'directive');
doc.pipes = doc.exports.filter(doc => doc.docType === 'pipe');
doc.types = doc.exports.filter(doc => doc.docType === 'type-alias' || doc.docType === 'const');
if (doc.exports.every(doc => !!doc.deprecated)) {
doc.deprecated = 'all exports of this entry point are deprecated.';
}
}
// Copy over docs from the PACKAGE.md file that is used to document packages
@ -58,6 +61,12 @@ module.exports = function processPackages() {
}
});
// Update package deprecation status (compared to entry point status)
Object.keys(packageMap).forEach(key => {
const pkg = packageMap[key];
pkg.primary.packageDeprecated = pkg.primary.deprecated !== undefined && pkg.secondary.every(entryPoint => entryPoint.deprecated !== undefined);
});
return docs;
}
};

110
aio/tools/transforms/angular-api-package/processors/processPackages.spec.js
View File

@ -9,8 +9,8 @@ describe('processPackages processor', () => {
const injector = dgeni.configureInjector();
const processor = injector.get('processPackages');
expect(processor.$process).toBeDefined();
expect(processor.$runAfter).toEqual(['extractDecoratedClassesProcessor']);
expect(processor.$runBefore).toEqual(['computing-ids']);
expect(processor.$runAfter).toEqual(['extractDecoratedClassesProcessor', 'computeStability']);
expect(processor.$runBefore).toEqual(['computing-ids', 'generateKeywordsProcessor']);
});
it('should filter out any `package-content` docs from the collection', () => {
@ -177,4 +177,110 @@ describe('processPackages processor', () => {
{ docType: 'const', id: 'const-2' },
]);
});
it('should compute the deprecated status of each entry point', () => {
const docs = [
{
fileInfo: { filePath: 'some/package-1/index' },
docType: 'module',
id: 'package-1',
exports: [
{ docType: 'class', id: 'class-1', deprecated: true },
]
},
{
fileInfo: { filePath: 'some/package-1/sub-1index' },
docType: 'module',
id: 'package-1/sub-1',
exports: [
{ docType: 'class', id: 'class-2', deprecated: true },
]
},
{
fileInfo: { filePath: 'some/package-2/index' },
docType: 'module',
id: 'package-2',
exports: [
{ docType: 'class', id: 'class-3' },
{ docType: 'class', id: 'class-4', deprecated: true },
]
},
{
fileInfo: { filePath: 'some/package-3/index' },
docType: 'module',
id: 'package-3',
exports: [
{ docType: 'class', id: 'class-5' },
{ docType: 'class', id: 'class-6' },
]
},
];
const processor = processorFactory();
const newDocs = processor.$process(docs);
expect(newDocs[0].deprecated).toBeTruthy();
expect(newDocs[1].deprecated).toBeTruthy();
expect(newDocs[2].deprecated).toBeUndefined();
expect(newDocs[3].deprecated).toBeUndefined();
});
it('should compute the deprecated status of packages', () => {
const docs = [
{
fileInfo: { filePath: 'some/package-1/index' },
docType: 'module',
id: 'package-1',
exports: [
{ docType: 'class', id: 'class-1', deprecated: true },
]
},
{
fileInfo: { filePath: 'some/package-1/sub-1index' },
docType: 'module',
id: 'package-1/sub-1',
exports: [
{ docType: 'class', id: 'class-2', deprecated: true },
]
},
{
fileInfo: { filePath: 'some/package-2/index' },
docType: 'module',
id: 'package-2',
exports: [
{ docType: 'class', id: 'class-3', deprecated: true },
]
},
{
fileInfo: { filePath: 'some/package-2/sub-1index' },
docType: 'module',
id: 'package-2/sub-1',
exports: [
{ docType: 'class', id: 'class-4', deprecated: false },
]
},
{
fileInfo: { filePath: 'some/package-3/index' },
docType: 'module',
id: 'package-3',
exports: [
{ docType: 'class', id: 'class-5', deprecated: false },
]
},
{
fileInfo: { filePath: 'some/package-3/sub-1index' },
docType: 'module',
id: 'package-3/sub-1',
exports: [
{ docType: 'class', id: 'class-6', deprecated: true },
]
},
];
const processor = processorFactory();
const newDocs = processor.$process(docs);
expect(newDocs[0].packageDeprecated).toBe(true);
expect(newDocs[1].packageDeprecated).toBeUndefined();
expect(newDocs[2].packageDeprecated).toBe(false);
expect(newDocs[3].packageDeprecated).toBeUndefined();
expect(newDocs[4].packageDeprecated).toBe(false);
});
});

3
aio/tools/transforms/angular-base-package/processors/generateKeywords.js vendored
View File

@ -140,7 +140,8 @@ module.exports = function generateKeywordsProcessor(log, readFilesProcessor) {
return Object.assign({
path: page.path,
title: page.searchTitle,
type: page.docType
type: page.docType,
deprecated: !!page.deprecated,
}, page.searchTerms);
});

3
aio/tools/transforms/angular-base-package/processors/generateKeywords.spec.js
View File

@ -166,7 +166,8 @@ describe('generateKeywords processor', () => {
'titleWords':'someclass',
'headingWords':'heading some someclass',
'keywords':'api class documentation for is someclass the',
'members':''
'members':'',
'deprecated': false,
}]
);
});

3
aio/tools/transforms/templates/api/base.template.html
View File

@ -16,12 +16,15 @@
</script>
{% for crumb in doc.breadCrumbs %}{% if not loop.last %} {$ breadcrumbDelimiter() $} {% if crumb.path %}<a href="{$ crumb.path $}">{$ crumb.text $}</a>{% else %}{$ crumb.text $}{% endif %}{% endif %}{% endfor %}
</div>
{% block header %}
<header class="api-header">
<h1>{$ doc.name $}</h1>
<label class="api-type-label {$ doc.docType $}">{$ doc.docType $}</label>
{% if doc.deprecated !== undefined %}<label class="api-status-label deprecated">deprecated</label>{% endif %}
{% if doc.security !== undefined %}<label class="api-status-label security">security</label>{% endif %}
{% if doc.pipeOptions.pure === 'false' %}<label class="api-status-label impure-pipe">impure</label>{% endif %}
</header>
{% endblock %}
<aio-toc class="embedded"></aio-toc>
<div class="api-body">

5
aio/tools/transforms/templates/api/includes/deprecation.html
View File

@ -1,6 +1,5 @@
{% if doc.deprecated %}
{% if doc.deprecated !== undefined %}
<section class="deprecated">
<h2>Deprecation notes</h2>
{$ doc.deprecated | marked $}
{$ ('**Deprecated:** ' + doc.deprecated) | marked $}
</section>
{% endif %}

3
aio/tools/transforms/templates/api/ngmodule.template.html
View File

@ -39,10 +39,11 @@
<tr>
<td>
<a href="{$ item.path $}">
<code-example language="ts" hideCopy="true" linenums="false" class="no-box">{$ item.name | escape $}</code-example>
<code-example language="ts" hideCopy="true" linenums="false" class="no-box{% if item.deprecated !== undefined %} deprecated-api-item{% endif %}">{$ item.name | escape $}</code-example>
</a>
</td>
<td>
{% if item.deprecated !== undefined %}{$ ('**Deprecated:** ' + item.deprecated) | marked $}{% endif %}
{$ item.shortDescription | marked $}
</td>
</tr>

21
aio/tools/transforms/templates/api/package.template.html
View File

@ -9,8 +9,13 @@
{% for item in filteredItems %}
<tr>
<td><code class="code-anchor">
<a href="{$ overridePath or item.path $}">{$ item.name $}</a></code></td>
<td>{% if item.shortDescription %}{$ item.shortDescription | marked $}{% endif %}</td>
<a href="{$ overridePath or item.path $}"
{%- if item.deprecated != undefined %} class="deprecated-api-item"{% endif %}>{$ item.name $}</a></code>
</td>
<td>
{% if item.deprecated !== undefined %}{$ ('**Deprecated:** ' + item.deprecated) | marked $}{% endif %}
{% if item.shortDescription %}{$ item.shortDescription | marked $}{% endif %}
</td>
</tr>
{% endfor %}
</table>
@ -18,8 +23,17 @@
{% endif %}
{% endmacro %}
{% block header %}
<header class="api-header">
<h1>{$ doc.name $}</h1>
<label class="api-type-label {$ doc.docType $}">{$ doc.docType $}</label>
{% if doc.packageDeprecated or (not doc.isPrimaryPackage and doc.deprecated !== undefined) %}<label class="api-status-label deprecated">deprecated</label>{% endif %}
{% if doc.security !== undefined %}<label class="api-status-label security">security</label>{% endif %}
{% if doc.pipeOptions.pure === 'false' %}<label class="api-status-label impure-pipe">impure</label>{% endif %}
</header>
{% endblock %}
{% block body -%}
{% include "includes/deprecation.html" %}
{$ doc.shortDescription | marked $}
{% if doc.description %}{$ doc.description | marked $}{% endif %}
@ -32,6 +46,7 @@
{% endif %}
<h2>{% if doc.isPrimaryPackage %}Primary entry{% else %}Entry{% endif %} point exports</h2>
{% include "includes/deprecation.html" %}
{$ listItems(doc.ngmodules, 'NgModules') $}
{$ listItems(doc.classes, 'Classes') $}
{$ listItems(doc.decorators, 'Decorators') $}