-
Notifications
You must be signed in to change notification settings - Fork 25.3k
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
feat(docs-infra): add support for "special elements" (#41299)
This commit adds support for generating pages that document special Angular elements, such as `ng-content` and `ng-template`, which have special behavior in Angular but are not directives nor components. Resolves #41273 PR Close #41299
- Loading branch information
1 parent
6bf4cb6
commit 9c9ae27
Showing
19 changed files
with
201 additions
and
25 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,28 @@ | ||
# Special Elements | ||
|
||
Each sub-directory below this contains documentation that describes "special elements". | ||
These are elements that can appear in templates that have special meaning and behaviour in the Angular framework. | ||
|
||
Each element should have a markdown file with the same file name as the element's tag name, e.g. `ng-container.md`. | ||
The file should be stored in a directory whose name is that of the Angular package under which this element should appear in the docs (usually `core`). | ||
|
||
## Short description | ||
|
||
The file should contain a "short description" of the element. This is the first paragraph in the file. | ||
|
||
## Long description | ||
|
||
All the paragraphs after the short description are collected as an additional longer description. | ||
|
||
## Element attributes | ||
|
||
If the special element accepts one or more attributes that have special meaning to Angular, then these should be documented using the `@elementAttribute` tag. | ||
These tags should come after the description. | ||
|
||
The format of this tag is: | ||
|
||
``` | ||
@elementAttribute attr="value" | ||
Description of the attribute and value. | ||
``` |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1 @@ | ||
The `<ng-container>` can be used to hold directives without creating an HTML element. |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,5 @@ | ||
The `<ng-content>` element specifies where to project content inside a component template. | ||
|
||
@elementAttribute select="selector" | ||
|
||
Only select elements from the projected content that match the given CSS `selector`. |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,3 @@ | ||
Angular's `<ng-template>` element defines a template that doesn't render anything by default. | ||
|
||
With `<ng-template>`, you can render the content manually for full control over how the content displays. |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
24 changes: 24 additions & 0 deletions
24
aio/tools/transforms/angular-api-package/processors/processSpecialElements.js
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,24 @@ | ||
const path = require('canonical-path'); | ||
|
||
module.exports = function processSpecialElements() { | ||
return { | ||
$runAfter: ['tags-extracted'], | ||
$runBefore: ['collectPackageContentDocsProcessor'], | ||
$process(docs) { | ||
const moduleDocs = {}; | ||
docs.forEach(doc => { | ||
if (doc.docType === 'module') { | ||
moduleDocs[doc.id] = doc; | ||
} | ||
}); | ||
|
||
docs.forEach(doc => { | ||
// Wire up each 'element' doc to its containing module/package. | ||
if (doc.docType === 'element') { | ||
doc.moduleDoc = moduleDocs[path.dirname(doc.fileInfo.relativePath)]; | ||
doc.moduleDoc.exports.push(doc); | ||
} | ||
}); | ||
} | ||
}; | ||
}; |
29 changes: 29 additions & 0 deletions
29
aio/tools/transforms/angular-api-package/readers/element.js
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,29 @@ | ||
/** | ||
* @dgService | ||
* @description | ||
* This file reader will pull the contents from a text file that will be used | ||
* as the description of a "special element", such as `<ng-content>` or `<ng-template>`, etc. | ||
* | ||
* The doc will initially have the form: | ||
* ``` | ||
* { | ||
* docType: 'element', | ||
* name: 'some-name', | ||
* content: 'the content of the file', | ||
* } | ||
* ``` | ||
*/ | ||
module.exports = function specialElementFileReader() { | ||
return { | ||
name: 'specialElementFileReader', | ||
defaultPattern: /\.md$/, | ||
getDocs: function(fileInfo) { | ||
// We return a single element array because element files only contain one document | ||
return [{ | ||
docType: 'element', | ||
name: `<${fileInfo.baseName}>`, | ||
content: fileInfo.content, | ||
}]; | ||
} | ||
}; | ||
}; |
24 changes: 24 additions & 0 deletions
24
aio/tools/transforms/angular-api-package/tag-defs/elementAttribute.js
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,24 @@ | ||
/** | ||
* Documents attributes that can appear on "special elements", such as `select` on `<ng-content>`. | ||
* | ||
* For example: | ||
* | ||
* ``` | ||
* @elementAttribute select="selector" | ||
* | ||
* Only select elements from the projected content that match the given CSS `selector`. | ||
* ``` | ||
*/ | ||
module.exports = function() { | ||
return { | ||
name: 'elementAttribute', | ||
docProperty: 'attributes', | ||
multi: true, | ||
transforms(doc, tag, value) { | ||
const startOfDescription = value.indexOf('\n'); | ||
const name = value.substring(0, startOfDescription).trim(); | ||
const description = value.substring(startOfDescription).trim(); | ||
return {name, description}; | ||
} | ||
}; | ||
}; |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,8 @@ | ||
{% extends 'export-base.template.html' -%} | ||
|
||
{% block overview %} | ||
{% include "includes/element-attributes.html" %} | ||
{% endblock %} | ||
{% block details %} | ||
{% include "includes/description.html" %} | ||
{% endblock %} |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
21 changes: 21 additions & 0 deletions
21
aio/tools/transforms/templates/api/includes/element-attributes.html
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,21 @@ | ||
{%- if doc.attributes %} | ||
<section class="element-attributes"> | ||
<h2>Attributes</h2> | ||
<table class="is-full-width list-table"> | ||
<thead> | ||
<tr> | ||
<th>Name</th> | ||
<th>Description</th> | ||
</tr> | ||
</thead> | ||
<tbody> | ||
{%- for attribute in doc.attributes %} | ||
<tr class="element-attribute"> | ||
<td><code>{$ attribute.name $}</code></td> | ||
<td>{$ attribute.description | marked $}</td> | ||
</tr> | ||
{% endfor %} | ||
</tbody> | ||
</table> | ||
</section> | ||
{% endif %} |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters