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

build(aio): big move of docs related files (#14361)

Browse Source 
All the docs related files (docs-app, doc-gen, content, etc)
are now to be found inside the `/aio` folder.

The related gulp tasks have been moved from the top level
gulp file to a new one inside the `/aio` folder.

The structure of the `/aio` folder now looks like:

```
/aio/
  build/         # gulp tasks
  content/       #MARKDOWN FILES for devguides, cheatsheet, etc
    devguides/
    cheatsheets/
  transforms/    #dgeni packages, templates, etc
  src/
    app/
    assets/
    content/    #HTML + JSON build artifacts produced by dgeni from /aio/content.
                #This dir is .gitignored-ed
  e2e/           #protractor tests for the doc viewer app
  node_modules/ #dependencies for both the doc viewer builds and the dgeni stuff
                #This dir is .gitignored-ed
  gulpfile.js   #Tasks for generating docs and building & deploying the doc viewer
```

Closes #14361
This commit is contained in:
Pete Bacon Darwin
2017-02-09 19:58:36 +00:00
committed by Igor Minar
parent 5e7a2fa854
commit 600402d440
437 changed files with 855 additions and 531 deletions
Download Patch File Download Diff File Expand all files Collapse all files

144
aio/transforms/templates/README.md Normal file
View File

@ -0,0 +1,144 @@
This folder contains the dgeni templates that are used to generate the API docs
Generally there is a template for each docType. Templates can extend and/or include
other templates. Templates can also import macros from other template files.
# Template inheritance
When extending a template, parent must declare blocks that can be overridden by the
child. The template extension hierarchy looks like this (with declared blocks in parentheses):
- layout/base.template.html (base)
- module.template.html
- layout/api-base.template.html (jumpNav, jumpNavLinks, whatItDoes, infoBar, securityConsiderations, deprecationNotes, howToUse, details)
- class.template.html
- directive.template.html
- enum.template.html
- var.template.html
- const.template.html
- let.template.html
- decorator.template.html
- function.template.html
- interface.template.html
- type-alias.template.html
- pipe.template.html
# Doc Properties
It is useful to know what properties are available on each doc type when working with the templates.
Here is an overview:
## class
- docType
- name
- id
- moduleDoc
- path
- description
- notYetDocumented
- members
## directive
- docType
- name
- id
- moduleDoc
- path
- description
- notYetDocumented
- members
## enum
- docType
- name
- id
- moduleDoc
- path
- description
- notYetDocumented
## var
- docType
- name
- id
- moduleDoc
- path
- description
- notYetDocumented
## const
- docType
- name
- id
- moduleDoc
- path
- description
- notYetDocumented
## let
- docType
- name
- id
- moduleDoc
- path
- description
- notYetDocumented
## decorator
- docType
- name
- id
- moduleDoc
- path
- description
- notYetDocumented
- members
## function
- docType
- name
- id
- moduleDoc
- path
- description
- notYetDocumented
## interface
- docType
- name
- id
- moduleDoc
- path
- description
- notYetDocumented
- members
## type-alias
- docType
- name
- id
- moduleDoc
- path
- description
- notYetDocumented
## pipe
- docType
- name
- id
- moduleDoc
- path
- description
- notYetDocumented

15
aio/transforms/templates/api-list-audit.template.json Normal file
View File

@ -0,0 +1,15 @@
[{% for module, items in doc.data %}
{% for item in items %}
{
"title": "{$ item.title $}",
"path": "{$ item.exportDoc.path $}",
"docType": "{$ item.docType $}",
"stability": "{$ item.stability $}",
"secure": "{$ item.security $}",
"howToUse": "{$ item.howToUse | replace('"','\\"') $}",
"whatItDoes": {% if item.whatItDoes %}"Exists"{% else %}"Not Done"{% endif %},
"barrel" : "{$ module | replace("/index", "") $}"
}{% if not loop.last %},{% endif %}
{% endfor %}
{% endfor %}
]

14
aio/transforms/templates/api-list-data.template.json Normal file
View File

@ -0,0 +1,14 @@
{
{%- for module, items in doc.data %}
"{$ module | replace("/index", "") $}" : [{% for item in items %}
{
"title": "{$ item.title $}",
"path": "{$ item.exportDoc.path $}",
"docType": "{$ item.docType $}",
"stability": "{$ item.stability $}",
"secure": "{$ item.security $}",
"barrel" : "{$ module | replace("/index", "") $}"
}{% if not loop.last %},{% endif %}
{% endfor %}]{% if not loop.last %},{% endif %}
{% endfor -%}
}

5
aio/transforms/templates/cheatsheet.template.json Normal file
View File

@ -0,0 +1,5 @@
{
"currentEnvironment": {$ doc.currentEnvironment | json | trim $},
"version": {$ doc.version.currentVersion | json | indent(2) | trim $},
"sections": {$ doc.sections | json | indent(2) | trim $}
}

12
aio/transforms/templates/class.template.html Normal file
View File

@ -0,0 +1,12 @@
{% import "lib/paramList.html" as params -%}
{% extends 'layout/api-base.template.html' -%}
{% block details %}
{% include "includes/_class-overview.html" %}
{% block additional %}{% endblock %}
{% include "includes/_description.html" %}
{% include "includes/_annotations.html" %}
{% include "includes/_constructor.html" %}
{% include "includes/_statics.html" %}
{% include "includes/_members.html" %}
{% endblock %}

1
aio/transforms/templates/const.template.html Normal file
View File

@ -0,0 +1 @@
{% extends 'var.template.html' -%}

2
aio/transforms/templates/content.template.html Normal file
View File

@ -0,0 +1,2 @@
<h1>{$ doc.title $}</h1>
{$ doc.description | marked $}

3
aio/transforms/templates/data-module.template.js Normal file
View File

@ -0,0 +1,3 @@
/* tslint:disable quotemark */
/* TODO: rework this so that it has single quotes */
export const {$ doc.serviceName $} = {$ doc.value | json $};

7
aio/transforms/templates/decorator.template.html Normal file
View File

@ -0,0 +1,7 @@
{% import "lib/paramList.html" as params -%}
{% extends 'layout/api-base.template.html' %}
{% block main %}
{% include "includes/_description.html" %}
{% include "includes/_metadata.html" %}
{% endblock %}

9
aio/transforms/templates/directive.template.html Normal file
View File

@ -0,0 +1,9 @@
{% import "lib/paramList.html" as params -%}
{% extends 'class.template.html' -%}
{% block additional -%}
{% include "includes/_selectors.html" %}
{% include "includes/_outputs.html" %}
{% include "includes/_inputs.html" %}
{% include "includes/_export-as.html" %}
{% endblock %}

1
aio/transforms/templates/enum.template.html Normal file
View File

@ -0,0 +1 @@
{% extends 'class.template.html' -%}

7
aio/transforms/templates/example-region.template.html Normal file
View File

@ -0,0 +1,7 @@
<div class="code-example">
{% marked %}
```
{$ doc.contents $}
```
{% endmarked %}
</div>

6
aio/transforms/templates/function.template.html Normal file
View File

@ -0,0 +1,6 @@
{% import "lib/paramList.html" as params -%}
{% extends 'layout/api-base.template.html' -%}
{% block main %}
{% include "includes/_description.html" %}
{% endblock %}

13
aio/transforms/templates/includes/_annotations.html Normal file
View File

@ -0,0 +1,13 @@
{%- if doc.decorators.length %}
<section class="annotations">
<h2>Annotations</h2>
<div class="annotation">
{%- for decorator in doc.decorators %}
<pre class="prettyprint no-bg">
<code>@{$ decorator.name $}{$ params.paramList(decorator.arguments) | indent(10, false) $}</code>
</pre>
{%- if not decorator.notYetDocumented %}{$ decorator.description | marked $}{% endif %}
{% endfor %}
</div>
</section>
{% endif %}

40
aio/transforms/templates/includes/_class-overview.html Normal file
View File

@ -0,0 +1,40 @@
<section class="class-overview">
<h2>Class Overview</h2>
<div class="api-doc-code">
<code class="no-bg openParens">class {$ doc.name $} {</code>
{% if doc.statics.length %}
<div class="statics">
{% for member in doc.statics %}{% if not member.internal %}
<pre class="prettyprint no-bg-with-indent"><code>static
<a class="code-anchor" href="#{$ member.name $}-anchor">{$ member.name | indent(6, false) | trim $}</a>
{$ params.paramList(member.parameters) | indent(8, false) | trim $}{$ params.returnType(member.returnType) $}
</code></pre>
{% endif %}{% endfor %}
</div>
{% endif %}
{% if doc.constructorDoc.name %}
<div class="constructor">
<pre class="prettyprint no-bg-with-indent"><code>
<a class="code-anchor" href="#constructor">{$ doc.constructorDoc.name $}</a>
{$ params.paramList(doc.constructorDoc.parameters) | indent(8, false) | trim $}
</code></pre>
</div>
{% endif %}
{% if doc.members.length %}
<div class="members">
{% for member in doc.members %}{% if not member.internal %}
<pre class="prettyprint no-bg-with-indent"><code>
<a class="code-anchor" href="#{$ member.name $}-anchor">{$ member.name | indent(6, false) | trim $}</a>
{$ params.paramList(member.parameters) | indent(8, false) | trim $}{$ params.returnType(member.returnType) $}
</code></pre>
{% endif %}{% endfor %}
{% endif %}
<code class="endParens api-doc-code no-bg">}</code>
</div>
</section>

16
aio/transforms/templates/includes/_constructor.html Normal file
View File

@ -0,0 +1,16 @@
{%- if doc.constructorDoc and not doc.constructorDoc.internal %}
<section class="constructor">
<h2>Constructor</h2>
<div class="description">
<a name="constructor" class="anchor-offset"></a>
<pre class="prettyprint no-bg" ng-class="{ 'anchor-focused': appCtrl.isApiDocMemberFocused('{$ doc.constructorDoc.name $}') }">
<code>
{$ doc.constructorDoc.name $}{$ params.paramList(doc.constructorDoc.parameters) | indent(8, false) | trim $}
</code>
</pre>
{%- if not doc.constructorDoc.notYetDocumented %}
{$ doc.constructorDoc.description | replace('### Example', '') | replace('## Example', '') | replace('# Example', '') | trimBlankLines | marked $}
{% endif %}
</div>
</section>
{% endif %}

11
aio/transforms/templates/includes/_deprecated-notes.html Normal file
View File

@ -0,0 +1,11 @@
{% if doc.showDeprecatedNotes %}
<div layout="row" layout-xs="column" class="row-margin ng-cloak">
<div flex="20" flex-xs="100">
<h2 class="h2-api-docs">Deprecation Notes</h2>
</div>
<div flex="80" flex-xs="100">
{%- if doc.deprecated %}{$ doc.deprecated | marked $}
{% else %}<em>Not yet documented</em>{% endif %}
</div>
</div>
{% endif %}

9
aio/transforms/templates/includes/_description.html Normal file
View File

@ -0,0 +1,9 @@
<section class="l-content-block">
<h3 class="text-display-1" id="api-description">
Description
<a href="#api-description" class="header-link"><i class="material-icons">link</i></a>
</h3>
{%- if doc.description.length > 2 %}
{$ doc.description | trimBlankLines | marked $}
{% endif %}
</section>

10
aio/transforms/templates/includes/_export-as.html Normal file
View File

@ -0,0 +1,10 @@
{%- if doc.directiveOptions.exportAs %}
<section class="export-as">
<h2>Exported as</h2>
<div class="description">
<p>
<code>{$ doc.directiveOptions.exportAs $}</code>
</p>
</div>
</section>
{% endif %}

9
aio/transforms/templates/includes/_how-to-use.html Normal file
View File

@ -0,0 +1,9 @@
{%- if doc.howToUse %}
<!-- QUICK REFERENCE CODE EXAMPLE -->
<section class="how-to-use">
<h2>How To Use</h2>
<div class="description">
{$ doc.howToUse | marked $}
</div>
</section>
{% endif %}

18
aio/transforms/templates/includes/_info-bar.html Normal file
View File

@ -0,0 +1,18 @@
{% import "lib/githubLinks.html" as github -%}
<!-- INFO BAR -->
<div class="info-bar">
<span class="info-bar-item is-left">
npm package: <a href="#">{$ doc.package $}</a>
</span>
<span class="info-bar-item is-left">
NgModule: <a href="#">{$ doc.moduleDoc.name $}</a>
</span>
<span class="info-bar-item is-right">
{$ github.githubViewLink(doc, versionInfo) $}
</span>
<i class="material-icons l-right">create</i>
</div>

13
aio/transforms/templates/includes/_inputs.html Normal file
View File

@ -0,0 +1,13 @@
{% if doc.inputs %}
<section class="inputs">
<h2>Inputs</h2>
<div class="description">
{% for binding, property in doc.inputs %}
<div class="input">
<code>{$ property.bindingName $}</code>&nbsp;bound to&nbsp;<code>{$ property.memberDoc.classDoc.name $}.{$ property.propertyName $}</code>
{$ property.memberDoc.description | trimBlankLines | marked $}
</div>
{% endfor %}
</div>
</section>
{% endif %}

19
aio/transforms/templates/includes/_interface-overview.html Normal file
View File

@ -0,0 +1,19 @@
<section class="class-overview">
<h2>Interface Overview</h2>
<div class="api-doc-code">
<code class="no-bg openParens">interface {$ doc.name $} {</code>
{% if doc.members.length %}
<div class="members">
{% for member in doc.members %}{% if not member.internal %}
<pre class="prettyprint no-bg-with-indent"><code>
<a class="code-anchor" href="#{$ member.name $}-anchor">{$ member.name | indent(6, false) | trim $}</a>
{$ params.paramList(member.parameters) | indent(8, false) | trim $}{$ params.returnType(member.returnType) $}
</code></pre>
{% endif %}{% endfor %}
{% endif %}
<code class="endParens api-doc-code no-bg">}</code>
</div>
</section>

19
aio/transforms/templates/includes/_members.html Normal file
View File

@ -0,0 +1,19 @@
{% if doc.members.length %}
<section class="instance-members">
<h2>Class Details</h2>
<div class="description">
{% for member in doc.members %}{% if not member.internal %}
<div class="instance-member">
<a name="{$ member.name $}-anchor" class="anchor-offset"></a>
<pre class="prettyprint no-bg" ng-class="{ 'anchor-focused': appCtrl.isApiDocMemberFocused('{$ member.name $}') }">
<code>{$ member.name $}{$ params.paramList(member.parameters) | trim $}{$ params.returnType(member.returnType) $}</code>
</pre>
{%- if not member.notYetDocumented %}
{$ member.description | replace('### Example', '') | replace('## Example', '') | replace('# Example', '') | trimBlankLines | marked $}
{% endif -%}
</div>
{% if not loop.last %}<hr class="hr-margin">{% endif %}
{% endif %}{% endfor %}
</div>
</section>
{% endif %}

17
aio/transforms/templates/includes/_metadata.html Normal file
View File

@ -0,0 +1,17 @@
{% if doc.members.length %}
<section class="meta-data">
<h2>Metadata Properties</h2>
<div class="description">
{% for metadata in doc.members %}{% if not metadata.internal %}
<div class="metadata-member">
<a name="{$ metadata.name $}-anchor" class="anchor-offset"></a>
<pre class="prettyprint no-bg" ng-class="{ 'anchor-focused': appCtrl.isApiDocMemberFocused('{$ metadata.name $}') }">
<code>{$ metadata.name $}{$ params.paramList(metadata.parameters) | trim $}{$ params.returnType(metadata.returnType) $}</code>
</pre>
{%- if not metadata.notYetDocumented %}{$ metadata.description | replace('### Example', '') | replace('## Example', '') | replace('# Example', '') | trimBlankLines | marked $}{% endif -%}
</div>
{% if not loop.last %}<hr class="hr-margin">{% endif %}
{% endif %}{% endfor %}
</div>
</section>
{% endif %}

8
aio/transforms/templates/includes/_ng-module.html Normal file
View File

@ -0,0 +1,8 @@
<div layout="row" layout-xs="column" class="row-margin ng-cloak">
<div flex="20" flex-xs="100">
<h2 class="h2-api-docs">NgModule</h2>
</div>
<div class="code-links" flex="80" flex-xs="100">
{$ doc.ngModule $}
</div>
</div>

13
aio/transforms/templates/includes/_outputs.html Normal file
View File

@ -0,0 +1,13 @@
{% if doc.outputs %}
<section class="outputs">
<h2>Outputs</h2>
<div class="description">
{% for binding, property in doc.outputs %}
<div class="output">
<code>{$ property.bindingName $}</code>&nbsp;bound to&nbsp;<code>{$ property.memberDoc.classDoc.name $}.{$ property.propertyName $}</code>
{$ property.memberDoc.description | trimBlankLines | marked $}
</div>
{% endfor %}
</div>
</section>
{% endif %}

10
aio/transforms/templates/includes/_security-notes.html Normal file
View File

@ -0,0 +1,10 @@
{% if doc.showSecurityNotes and doc.security %}
<div layout="row" layout-xs="column" class="row-margin ng-cloak">
<div flex="20" flex-xs="100">
<h2 class="h2-api-docs">Security Risk</h2>
</div>
<div flex="80" flex-xs="100">
{$ doc.security | marked $}
</div>
</div>
{% endif %}

12
aio/transforms/templates/includes/_selectors.html Normal file
View File

@ -0,0 +1,12 @@
{%- if doc.directiveOptions.selector.split(',').length %}
<section class="selectors">
<h2>Selectors</h2>
<div class="description">
{% for selector in doc.directiveOptions.selector.split(',') %}
<p class="selector">
<code>{$ selector $}</code>
</p>
{% endfor %}
</div>
</section>
{% endif %}

23
aio/transforms/templates/includes/_statics.html Normal file
View File

@ -0,0 +1,23 @@
{% if doc.statics.length %}
<section class="static-members">
<h2>Static Members</h2>
<div class="description">
{% for member in doc.statics %}{% if not member.internal %}
<div class="static-member">
<a name="{$ member.name $}-anchor" class="anchor-offset"></a>
<pre class="prettyprint no-bg" ng-class="{ 'anchor-focused': appCtrl.isApiDocMemberFocused('{$ member.name $}') }">
<code>{$ member.name $}{$ params.paramList(member.parameters) | trim $}{$ params.returnType(member.returnType) $}</code>
</pre>
{%- if not member.notYetDocumented %}
{$ member.description | replace('### Example', '') | replace('## Example', '') | replace('# Example', '') | trimBlankLines | marked $}
{% endif %}
</div>
{% if not loop.last %}
<hr class="hr-margin">
{% endif %}
{% endif %}{% endfor %}
</div>
</section>
{% endif %}

6
aio/transforms/templates/includes/_title.html Normal file
View File

@ -0,0 +1,6 @@
<!-- PAGE HERO -->
<header>
<h1>{$ doc.name $}</h1>
<h2>{$ doc.docType $}</h2>
<span class="version">{$ angular.version $}</span>
</header>

3
aio/transforms/templates/includes/_what-it-does.html Normal file
View File

@ -0,0 +1,3 @@
{%- if doc.whatItDoes %}
<div class="what-it-does">{$ doc.whatItDoes | marked $}</div>
{% endif %}

8
aio/transforms/templates/interface.template.html Normal file
View File

@ -0,0 +1,8 @@
{% import "lib/paramList.html" as params -%}
{% extends 'layout/api-base.template.html' -%}
{% block main %}
{% include "includes/_interface-overview.html" %}
{% include "includes/_description.html" %}
{% include "includes/_members.html" %}
{% endblock %}

1
aio/transforms/templates/json-doc.template.json Normal file
View File

@ -0,0 +1 @@
{$ doc.data | json $}

11
aio/transforms/templates/layout/api-base.template.html Normal file
View File

@ -0,0 +1,11 @@
{% extends 'layout/base.template.html' -%}
{% block body %}
<aio-jump-nav></aio-jump-nav>
{% include "includes/_what-it-does.html" %}
{% include "includes/_info-bar.html" %}
{% include "includes/_security-notes.html" %}
{% include "includes/_deprecated-notes.html" %}
{% include "includes/_how-to-use.html" %}
{% block details %}{% endblock %}
{% endblock %}

4
aio/transforms/templates/layout/base.template.html Normal file
View File

@ -0,0 +1,4 @@
<article>
{% include "includes/_title.html" %}
{% block body %}{% endblock %}
</article>

1
aio/transforms/templates/let.template.html Normal file
View File

@ -0,0 +1 @@
{% extends 'var.template.html' -%}

7
aio/transforms/templates/lib/githubLinks.html Normal file
View File

@ -0,0 +1,7 @@
{% macro githubHref(doc, versionInfo) -%}
https://github.com/{$ versionInfo.gitRepoInfo.owner $}/{$ versionInfo.gitRepoInfo.repo $}/tree/{$ versionInfo.currentVersion.isSnapshot and versionInfo.currentVersion.SHA or versionInfo.currentVersion.raw $}/modules/{$ doc.fileInfo.projectRelativePath $}#L{$ doc.location.start.line+1 $}-L{$ doc.location.end.line+1 $}
{%- endmacro %}
{% macro githubViewLink(doc, versionInfo) -%}
<a href="{$ githubHref(doc, versionInfo) $}">{$ doc.fileInfo.projectRelativePath $}</a>
{%- endmacro %}

12
aio/transforms/templates/lib/paramList.html Normal file
View File

@ -0,0 +1,12 @@
{% macro paramList(params) -%}
{%- if params -%}
({%- for param in params -%}
{$ param | escape $}{% if not loop.last %}, {% endif %}
{%- endfor %})
{%- endif %}
{%- endmacro -%}
{% macro returnType(returnType) -%}
{%- if returnType %} : {$ returnType | escape $}{% endif -%}
{%- endmacro -%}

12
aio/transforms/templates/module.template.html Normal file
View File

@ -0,0 +1,12 @@
{% extends 'layout/base.template.html' -%}
{% block body -%}
<ul>
{% for page in doc.childPages -%}
<li>
<!-- TODO: convert to hovercard -->
<a href="{$ relativePath(doc.moduleFolder, page.exportDoc.path) $}">{$ page.title $}</a>
</li>
{% endfor %}
</ul>
{% endblock %}

74
aio/transforms/templates/overview-dump.template.html Normal file
View File

@ -0,0 +1,74 @@
{% import "lib/githubLinks.html" as github -%}
{% import "lib/paramList.html" as params -%}
<!DOCTYPE html>
<html>
<head>
<title></title>
<style>
body {
max-width: 1000px;
}
h2 {
margin-top: 20px;
margin-bottom: 0;
border-bottom: solid 1px black;
}
h3 {
margin-top: 10px;
margin-bottom: 0;
padding-left: 20px;
}
h4 {
padding-left: 30px;
margin: 0;
}
.not-documented::after {
content: "(not documented)";
font-size: small;
font-style: italic;
color: red;
}
a {
color: black;
text-decoration: none;
}
</style>
</head>
<body>
<h1>Module Overview</h1>
{% for module in doc.modules %}
<h2>
<code>{$ module.id $}{%- if module.public %} (public){% endif %}</code>
</h2>
{% for export in module.exports %}
<h3 {% if export.notYetDocumented %}class="not-documented"{% endif %}>
<a href="{$ github.githubHref(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.githubHref(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.githubHref(member, versionInfo) $}">
<code>{$ member.name $}{$ params.paramList(member.params) $}</code>
</a>
</h4>
{% endfor %}
{% endfor %}
{% endfor %}
</body>
</html>

5
aio/transforms/templates/pipe.template.html Normal file
View File

@ -0,0 +1,5 @@
{% extends 'layout/api-base.template.html' -%}
{% block details %}
{% include "includes/_description.html" %}
{% endblock %}

1
aio/transforms/templates/type-alias.template.html Normal file
View File

@ -0,0 +1 @@
{% extends 'interface.template.html' %}

5
aio/transforms/templates/var.template.html Normal file
View File

@ -0,0 +1,5 @@
{% extends 'layout/api-base.template.html' %}
{% block details %}
{% include "includes/_description.html" %}
{% endblock %}