Skip to content
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

Jump to bottom

build(aio): render doc-gen issues in overview dump #22675

Closed
wants to merge 1 commit into from
Closed

build(aio): render doc-gen issues in overview dump #22675

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Jump to
Jump to file
Failed to load files.
Diff view
Diff view
1 change: 1 addition & 0 deletions aio/tools/transforms/angular-api-package/tag-defs/howToUse.js
View file
Open in desktop
@@ -1,6 +1,7 @@
module.exports = function(log, createDocMessage) {
return {
name: 'howToUse',
deprecated: true,
transforms(doc, tag, value) {
log.warn(createDocMessage('Deprecated `@howToUse` tag found', doc));
log.warn('PLEASE FIX by renaming to `@usageNotes.');
Expand Down
1 change: 1 addition & 0 deletions aio/tools/transforms/angular-api-package/tag-defs/stable.js
View file
Open in desktop
@@ -1,6 +1,7 @@
module.exports = function(log, createDocMessage) {
return {
name: 'stable',
deprecated: true,
transforms(doc, tag, value) {
log.warn(createDocMessage('Deprecated `@stable` tag found', doc));
log.warn('PLEASE REMOVE - its value is now computed.');
Expand Down
1 change: 1 addition & 0 deletions aio/tools/transforms/angular-api-package/tag-defs/whatItDoes.js
View file
Open in desktop
@@ -1,6 +1,7 @@
module.exports = function(log, createDocMessage) {
return {
name: 'whatItDoes',
deprecated: true,
transforms(doc, tag, value) {
log.warn(createDocMessage('Deprecated `@whatItDoes` tag found', doc));
log.warn('PLEASE FIX by adding the content of this tag as the first paragraph of the `@description` tag.');
Expand Down
1 change: 0 additions & 1 deletion aio/tools/transforms/angular-base-package/index.js
View file
Open in desktop
Expand Up @@ -24,7 +24,6 @@ module.exports = new Package('angular-base', [

// Register the processors
.processor(require('./processors/generateKeywords'))
.processor(require('./processors/createOverviewDump'))
.processor(require('./processors/createSitemap'))
.processor(require('./processors/checkUnbalancedBackTicks'))
.processor(require('./processors/convertToJson'))
Expand Down
1 change: 1 addition & 0 deletions aio/tools/transforms/angular.io-package/index.js
View file
Open in desktop
Expand Up @@ -17,6 +17,7 @@ module.exports = new Package('angular.io', [gitPackage, apiPackage, contentPacka

// This processor relies upon the versionInfo. See below...
.processor(require('./processors/processNavigationMap'))
.processor(require('./processors/createOverviewDump'))
.processor(require('./processors/cleanGeneratedFiles'))

// We don't include this in the angular-base package because the `versionInfo` stuff
Expand Down
0 ...-package/processors/createOverviewDump.js → ...-package/processors/createOverviewDump.js
View file
Open in desktop
File renamed without changes.
124 changes: 80 additions & 44 deletions aio/tools/transforms/templates/overview-dump.template.html
View file
Open in desktop
@@ -1,74 +1,110 @@
{% import "api/lib/githubLinks.html" as github -%}
{% import "api/lib/paramList.html" as params -%}
{% import "api/lib/memberHelpers.html" as members -%}
{% macro goToCode(doc) %}<a href="{$ github.githubViewHref(doc, versionInfo) $}" class="go-to-code" title="Go to source code"><i class="material-icons" aria-hidden="true" role="img">code</i></a>{% endmacro %}
{% macro label(test, class, text) %}{% if test %}<label class="{$ class $}">{$ text $}</label>{% endif %}{% endmacro %}
{% macro renderLabels(doc) -%}
{$ label(doc.notYetDocumented, 'no-doc', 'UNDOCUMENTED') $}
{%- for tag in doc.tags.tags %}{$ label(tag.tagDef.deprecated, 'deprecated', '@' + tag.tagDef.name + ' deprecated') $}{% endfor %}
{% endmacro %}
{% macro renderMember(member) -%}
<div class="member">{$ goToCode(member) $}
<h4><code>{$ members.renderMemberSyntax(member, 1) $}</code></h4>
{$ renderLabels(member) $}
</div>
{% endmacro -%}

<!DOCTYPE html>
<html>
<head>
<title></title>
<link href="https://fonts.googleapis.com/icon?family=Material+Icons" rel="stylesheet">
<style>
body {
max-width: 1000px;
margin: 0 50px;
}
details {
margin: 10px;
padding: 0 10px;
border: solid black 1px;
}
details details {
border: none;
margin: 0;
}

.member:nth-child(odd) {
background-color: #eee;
}
h2 {
margin-top: 20px;
margin-bottom: 0;
border-bottom: solid 1px black;
h2, h3, h4 {
display: inline-block;
margin: 0;
}
h3 {
margin-top: 10px;
margin-bottom: 0;
padding-left: 20px;
padding-left: 15px;
}
h4 {
padding-left: 30px;
margin: 0;
padding: 10px 0 0 30px;
}
.not-documented::after {
content: "(not documented)";
font-size: small;
font-style: italic;
color: red;
div {
position: relative;
}

label {
border-radius: 4px;
padding: 4px 8px;
display: inline-block;
font-size: 12px;
color: #fff;
margin: 0 8px;
font-weight: bold;
font-family: Arial, Helvetica, sans-serif;
}
a {

.no-doc {
background-color: red;
}

.deprecated {
background-color: orange;
color: black;
text-decoration: none;
}

a.go-to-code {
position: absolute;
top: 10px;
right: 10px;
}
</style>
</head>
<body>


<h1>Module Overview</h1>
<h1>Documentation Status Report</h1>

{% for module in doc.modules %}

<h2>
<code>{$ module.id $}{%- if module.public %} (public){% endif %}</code>
</h2>
<details>
<summary><h2><code>{$ module.id $}{%- if module.public %} (public){% endif %}</code></h2></summary>

{% for export in module.exports %}
<h3 {% if export.notYetDocumented %}class="not-documented"{% endif %}>
<a href="{$ github.githubViewHref(export, versionInfo) $}">
<code>{$ export.docType $} {$ export.name $}</code>
</a>
</h3>
{%- if export.constructorDoc %}
<h4 {% if export.constructorDoc.notYetDocumented %}class="not-documented"{% endif %}>
<a href="{$ github.githubViewHref(export.constructorDoc, versionInfo) $}">
<code>{$ export.constructorDoc.name $}{$ params.paramList(export.constructorDoc.params) $}</code>
</a>
</h4>
{% endif -%}
{%- for member in export.members %}
<h4 {% if member.notYetDocumented %}class="not-documented"{% endif %}>
<a href="{$ github.githubViewHref(member, versionInfo) $}">
<code>{$ member.name $}{$ params.paramList(member.params) $}</code>
</a>
</h4>
{% endfor %}
<div class="export">{$ goToCode(export) $}
<details>
<summary><h3><code>{$ export.docType $} {$ export.name $}</code></h3>{$ renderLabels(export) $}</summary>

{% endfor %}
{%- for member in export.staticProperties %}{% if not member.internal %}
{$ renderMember(member) $}</a>{% endif %}{% endfor -%}
{% for member in export.staticMethods %}{% if not member.internal %}
{$ renderMember(member) $}</a>{% endif %}{% endfor -%}
{% if export.constructorDoc and not export.constructorexport.internal %}
{$ renderMember(export.constructorDoc) $}</a>{% endif -%}
{% for member in export.properties %}{% if not member.internal %}
{$ renderMember(member) $}</a>{% endif %}{% endfor -%}
{% for member in export.methods %}{% if not member.internal %}
{$ renderMember(member) $}</a>{% endif %}{% endfor -%}

</details>
</div>
{% endfor %}
</details>
{% endfor %}

</body>
</html>