Decorator API pages list all their available options in an overview
table and also in a detailed view. Now the rendered syntax of each
option will show a `?` after the name if the option is not required.
This is inline with how class and interface members are rendered.
PR Close#39167
Previously, when updating the dependency versions in
`aio/tools/examples/shared/package.json` (which contains all
dependencies used in docs examples projects), one had to manually go
through all boilerplate directories and update the `package.json` files
with the same versions.
This commit simplifies this task by automating it via a Node.js script.
PR Close#38992
When updating the boilerplate for CLI-based docs examples, one needed to
install dependencies inside the
`aio/tools/examples/shared/boilerplate/cli/` directory, which resulted
in a `node_modules/` directory and a `yarn.lock` file. These were not
supposed to be part of the boilerplate, so they had to be manually
removed after the boilerplate was updated.
This commit simplifies the workflow by allowing boilerplate files to be
ignored (both by git and the `example-boilerplate.js` script) via a
`.gitignore` file. This way, it is no longer necessary to manually
remove the unneeded directories/files.
PR Close#38992
This commit updates the Markdown files inside the `aio/tools/` directory
to contain one sentence per line in order to be consistent with how
Markdown files are formatted in the rest of the repo.
PR Close#38992
Remove @angular/platform-webworker and @angular/platform-webworker-dynamic
as they were deprecated in v8
BREAKING CHANGE: @angular/platform-webworker and @angular/platform-webworker-dynamic
have been removed as they were deprecated in v8
PR Close#38846
In the past, the docs examples were configured to not use AOT
compilation in development mode (only in production mode). This was an
artifact of when JIT was the default in development mode.
Now that AOT is the default (even in development mode) for new CLI apps,
this commit configures all docs examples to always use AOT compilation.
(This has been made possible by fixing the `component-interaction` docs
example to correctly run in AOT mode in an earlier commit.)
PR Close#39001
This commit updates the docs examples to Angular v10.1.3. In addition to
updating the dependencies versions, it also updates the project's
structure and config to more closely match what a new v10 CLI app would
look like. See, also, the [diff][1] between a basic v9.1.4 CLI app and a
v10.1.3 one.
[1]: https://github.com/cexbrayat/angular-cli-diff/compare/9.1.4..10.1.3
PR Close#38993
Data in events page was hardcoded and it is manually moved in the table.
Created a new events widget which will automatically move past and upcoming
events from events.json (`aio/content/marketing/events.json`) file to the
relevant table in the events tab
PR Close#36517
Previously, the [processCliCommands][1] dgeni processor, which is used
to generate the docs pages for the CLI commands, expected the CLI
commands overview page (with a URL of `cli`) to exist as a child of a
top-level navigation section (`CLI Commands`). If one tried to move the
`CLI Commands` section inside another section, `processCliCommnads`
would fail to find it and thus fail to generate the CLI commands docs.
This problem came up in #38353.
This commit updates the `processCliCommands` processor to be able to
find it regardless of the position of the `CLI Commands` section inside
the navigation doc.
[1]:
dca4443a8e/aio/tools/transforms/cli-docs-package/processors/processCliCommands.js (L7-L9)
PR Close#38365
This commit updates the `tslint.json` configuration file, that is used
to lint the docs examples, to match the one generated for new Angular
CLI apps. There are some minimal differences (marked with `TODO`
comments) for things, such as component selector prefix, that would
require extensive and/or difficult to validate changes in guides.
This commit also includes the final adjustments to make the docs
examples code compatible with the new tslint rules. (The bulk of the
work has been done in previous commits.)
PR Close#38143
Previously, `ExampleZipper` (the tool used for creating ZIP archives
from our docs examples) used the `PackageJsonCustomizer` to generate
`package.json` files for each example type. This had the following
drawbacks:
- The generated files had to be kept up-to-date with the corresponding
boilerplate files in `aio/tools/examples/shared/boilerplate/` and
there was no easy way to find out when the files got out-of-sync.
- The `PackageJsonCustomizer` logic was non-trivial and difficult to
reason about.
- The same information was duplicated in the boilerplate files and the
customizer configuration files.
This setup was useful when we used a single `package.json` file for all
docs examples. Now, however, each example type can have its own
boilerplate `package.json` file, including scripts and dependencies
relevant to the example type. Therefore, it is no longer necessary to
generate `package.json` files for ZIP archives.
This commit eliminates the drawbacks mentioned above and simplifies the
`ExampleZipper` tool by removing `PackageJsonCustomizer` and re-using
the boilerplate `package.json` files for ZIP archives.
The changes in this commit also fix some ZIP archives that were
previously broken (for example due to missing dependencies).
PR Close#38192
To avoid unnecessary code duplication in docs examples, we have some
boilerplate files for various example types (in
`aio/tools/examples/shared/boilerplate/`). These files are copied to
each example project in `aio/content/examples/` (according to the
example's type, as specified in its `example-config.json` file).
Previously, the `example-boilerplate.js`, which is responsible for
copying the boilerplate files, had lists for files to be copied for each
project type and only copied the listed files from the boilerplate
directory to the example directory. This approach had some drawbacks:
- Files need to be updated in two separate locations: in the boilerplate
directory that includes the files and the file list in
`example-boilerplate.js`.
- It is easy to add a file in the boilerplate directory but forget to
add it in `example-boilerplate.js` and not realize that it is not
being included in the example project (including the generated
StackBlitz project and ZIP archive).
This commit changes the approach by removing the boilerplate file
listings from `example-boilerplate.js` and copying all files from a
boilerplate directory to example directories. This addresses the above
drawbacks and simplifies the `example-boilerplate.js` script.
I have verified that the resulting code example doc regions as well as
the generated StackBlitz projects and ZIP archives are identical to the
ones generated before this commit.
PR Close#38173
Previously, the `.gitignore` file that is part of the boilerplate files
for CLI-based docs examples (located in
`aio/tools/examples/shared/boilerplate/cli/`) was not added to the
example projects, because it was not included in the boilerplate file
list in `example-boilerplate.js`.
This commit fixes it by adding the `.gitignore` file to the list. This
ensures that docs examples more closely match CLI-generated projects.
PR Close#38173
Docs examples of type `i18n` need a slightly modified version of
`polyfills.ts` that imports `@angular/localize/init`. Previously, this
file was not included in `i18n` example projects for two reasons:
- While the file was included in the `i18n` boilerplate files (at
`aio/tools/examples/shared/boilerplate/i18n/`), it was not included in
the boilerplate file list in `example-boilerplate.js`.
- The file was in the wrong location: It was located at the project root
instead of inside the `src/` directory.
This commit addresses the above issues (i.e. adds the file to the
boilerplate file list for `i18n` projects and moves the file inside the
`src/` directory).
PR Close#38173
There were some `systemjs.config.web[.build].js` files in the `systemjs`
boilerplate directory that are not used any more. In the past, these
files were used in the Plunker-based live examples, but we no longer use
Plunker for live examples.
This commit removes these obsolete files.
PR Close#38173
There were two `typings.d.ts` files with SystemJS module definitions in
`aio/src/` and `aio/tools/examples/shared/boilerplate/cli/`. These are
remnants from old CLI versions that used SystemJS and are no longer
needed. For docs examples specifically, these files were never copied
over to example projects and thus not included in StackBlitz projects
and ZIP archives.
This commit removes these obsolete files.
PR Close#38173
In `aio/`, we have a mechanism to apply patches in a `postinstall` hook.
See `aio/tools/cli-patches/README.md` for more info.
Previously, we had to update `aio/tools/cli-patches/patch.js` to list
each `.patch` file separately. While working on #37688, I found it
helpful for the script to automatically pick up `.patch` files.
This commit updates the script to automatically pick up and apply
`.patch` files from the `aio/tools/cli-patches/` directory. If one wants
to keep a `.patch` file but not apply it, they can change the file's
extension or move it to a sub-directory (without having to update the
script).
PR Close#37896
`skipLibCheck` had to be added to a few AIO examples, because of a breaking change in master. These changes update to a newer version of `angular-in-memory-web-api` that accounts for the breaking change.
PR Close#37128
Previously this inline-tag-def was returning the `doc` which is rendered
to the output as `[Object Object]` - obviously not what is intended.
Now it returns `''` which effectively strips the tag handler from the
rendered output.
PR Close#37132
In the code base there are cases where there is, conceptually, a class
that is represented by a combination of an `interface`
(type declaration) and a `const` (value declaration).
For example:
```
export interface SomeClass {
count(a?: string): number;
}
export const: SomeClass = class {
someMethod(a: string = ''): number { ... }
};
```
These were being rendered as interfaces and also not
correctly showing the descriptions and default parameter
values.
In this commit such concepts are now rendered as classes.
The classes that are affected by this are:
* `DebugElement`
* `DebugNode`
* `Type`
* `EventEmitter`
* `TestBed`
Note that while decorators are also defined in this form
they have their own rendering type (`decorator`) and so
are not affecte by this.
PR Close#36989
We recently disabled the e2e tests for `upgrade-phonecat-2-hybdrid`
because the switch to APF 10 caused it to fail with an uglify
error. More details in a dedicated issue here:
https://github.com/angular/angular/issues/36957.
We can re-enable the test by switching to Terser that properly
handles ES2015 syntax. Previously the rollup bundle consisted
only of ES5 output as the Angular framework packages provided
ES5 output. With APF 10, there is no ES5 output except for the
non-optimizable UMD format.
Hence we either need to downlevel code to ES5, or use Terser
that supports ES2015 syntax.
Closes#36957.
PR Close#36969
Abstract directives cannot be part of a `@NgModule`, but the AIO dgeni
setup currently enforces this. This commit updates the logic so that
abstract directives are skipped.
PR Close#36921
In v9, we deprecated the use of ModuleWithProviders
without a generic. In v10, we will be requiring the
generic when using ModuleWithProviders. You can read
more about the reasoning behind this change in the
migration guide:
http://v9.angular.io/guide/migration-module-with-providers
PR Close#36892
This commit also updates the projects to more closely match what a newly
generated app would look like with the exception of `tslint.json` files,
which would create too many linting failures. These will be updated in a
follow-up PR.
PR Close#36145
Previously, when a document included `_`, the autoLinker will try to
generate a link, e.g from `core/ɵComponentDef._`. This commit adds it
to the ignored words to prevent that.
PR Close#36316
Previously, the auto linker generated links without an `href` when the
API was private. This commit fixes this by making sure that the `path`
of the document is not empty.
Closes#36260
PR Close#36316
Previously, building the `universal` example failed with:
```
node_modules/@types/express/index.d.ts(90,50): error TS2694: Namespace '".../@types/express-serve-static-core/index"' has no exported member 'Params'.
node_modules/@types/express/index.d.ts(90,64): error TS2694: Namespace '".../@types/express-serve-static-core/index"' has no exported member 'ParamsDictionary'.
```
This commit fixes the error by upgrading
`@types/express-serve-static-core` to a newer version.
See DefinitelyTyped/DefinitelyTyped#40905 for more details.
PR Close#36483
Previously, the `package.json` template used in the ZIP archive of the
`universal` example that we offer for download missed the `build` npm
script.
This commit updates the template for the `universal` docs example to
include the `build` npm script.
NOTE:
The `build` npm script is already included in
`aio/tools/examples/shared/boilerplate/universal/package.json`, but it
was removed by the example zipper.
PR Close#36483
Previously, the `elements` docs example only worked in browsers that
natively supported Custom Elements and ES2015 modules. Furthermore, it
didn't work on StackBlitz, because StackBlitz ignores the specified
`target` in `tsconfig.json` and uses the UMD bundles (i.e. ES5 code)
even on browsers that do support ES2015.
(NOTE: In the past, this was not a problem, because we explicitly did
not provide a StackBlitz example. This has changed in #36067.)
This commit ensures the example works on all browsers and also on
StackBlitz by providing the necessary Custom Elements polyfills.
Fixes#36532
PR Close#36536
Each docs example has an `example-config.json` configuration file. Among
other things, this file can be used to specify what commands to run in
order to test the example. (If not specified, the `run-example-e2e.js`
script will run a default `yarn e2e` command.)
Previously, the property specifying the test commands was called `e2e`.
This is because in the past only e2e tests were run for docs examples.
Since recently, some examples may specify commands for other types of
tests (such as unit tests). Therefore, calling the property that holds
the list of test commands `e2e` no longer makes sense and can be
misleading to people looking at the configuration files.
This commit renamed the property to the more generic `tests`. In the
future, the `run-example-e2e.js` script (and corresponding npm script)
should be renamed and refactored to also avoid giving the impression
that only e2e tests are run.
Discussed in:
https://github.com/angular/angular/pull/36143#discussion_r395148379
PR Close#36143
The `core-js` dependency is no longer included in `package.json` for
`cli`-type examples, but only for the `systemjs` ones. This commit
updates the `package.json` templates to reflect that (and also updates
the `npm-packages` guide accordingly).
PR Close#36143
Previously, only e2e tests were run for docs examples on CI. As a
result, unit tests (which are included in the zipped archives we provide
for users to download and play with the examples locally) were often
outdated and broken.
This commit configures specific docs examples that have meaningful unit
tests to run them on CI (via the `run-example-e2e.js` script). Where
necessary, the unit tests are fixed to ensure they pass and reflect the
changes in the corresponding component/service.
This commit also removes some auto-generated unit tests that are not
meaningful (e.g. make trivial assertions, such that a component instance
is truthy) and are often broken anyway (e.g. because the corresponding
component has been changed in ways that make the tests fail).
PR Close#36143
In #35381, a new Protractor config file was introduced in docs examples,
`protractor-puppeteer.conf.js`, that was only supposed to be used on CI
and not be shipped with the ZIP archives provided for users to download
and experiment with the docs examples locally.
The logic to ignore the `protractor-puppeteer.conf.js` file was
incorrect, resulting in the file being retained in some examples (e.g.
[universal][1]). The problem was not immediately obvious, because most
examples explicitly specify all `**/*.js` files as ignored, but for
other examples the file was retained in the ZIP archive.
This commit fixes the logic to ensure the file is excluded from all docs
examples ZIP archives.
[1]: https://v9.angular.io/generated/zips/universal/universal.zip
PR Close#36018
The `removeSystemJsConfig` and `type` properties (present in some
`zipper.json` files) are now obsolete and are not taken into account by
the example zipper:
- `removeSystemJsConfig` is no longer relevant since most examples have
been migrated to use the CLI.
- `type` is no longer relevant, because the project type is determined
based on the `projectType` property in `example-config.json` files.
This commit removes these properties from `zipper.json` files and
updates the `example-zipper` docs to not mention them.
PR Close#36018
Previously, all StackBlitz examples included the default dependencies
for `cli`-type projects. However, different example types may have
different `package.json` files with different dependencies.
For example, the [boilerplate `package.json`][1] for `elements` examples
includes an extra dependency on `@angular/elements`.
This commit changes `StackblitzBuilder` to use the dependencies that
correspond to each example type.
(NOTE: Manually verified the changes.)
Jira issue: [FW-2002][2]
[1]: https://github.com/angular/angular/blob/05d058622/aio/tools/examples/shared/boilerplate/elements/package.json
[2]: https://angular-team.atlassian.net/browse/FW-2002
PR Close#36071
Previously, the `package.json` files added as boilerplate to docs
example projects of type `systemjs` were incorrect/outdated. They
contained unused dependencies and npm scripts and omitted used
dependencies.
This is not a big issue, because these examples are not offered as live
StackBlitz examples or downloadable ZIP archives, but having incorrect
`package.json` files is confusing and makes it more complicated to
update these examples.
This commit updates the `package.json` templates for the `systemjs` docs
examples and other configuration files to include used dependencies (and
remove unused ones). It also removes unused npm scripts.
PR Close#36015
Update dependencies.
Also, disable AOT tests for `systemjs`-type examples in Ivy mode,
because our current setup does not work with v9. See #35989 for details.
Fixes#34382Fixes#34383
PR Close#36015
Update `tsconfig[.*].json`.
Also, all make necessary changes to ensure the example apps can be
successfully built with the new, stricter type-checking options.
PR Close#36015
In some cases, we want to test the AIO app or docs examples against the
locally built Angular packages (for example to ensure that the changes
in a commit do not introduce a breaking change). In order to achieve
this, we have the `ng-packages-installer` script that handles updating
a project's `package.json` file to use the locally built Angular
packages (and appropriate versions for their (dev-/peer-)dependencies).
Previously, `ng-packages-installer` would only consider the locally
built Angular packages (from `dist/packages-dist/`). However, given that
Zone.js is now part of the `angular/angular` repo, it makes sense to
also use the locally built Zone.js package (from `dist/zone.js-dist/`).
Otherwise, the tests might fail for commits that update both the Angular
packages (and related docs examples) and the Zone.js package. An example
of such a simultaneous change (that would have broken tests) is #33838.
This commit updates the script to install the locally built Zone.js
package (in addition to the Angular ones). The commit ensures that the
Zone.js package will always be available alongside the Angular packages
(i.e. that the Zone.js package will be built by the same script that
builds the Angular packages and that the `dist/zone.js-dist/` directory
will be cached on CI).
Note: This problem was discovered while enabling docs examples unit
tests in #34374.
PR Close#35858
This reverts commit 7d832ae1001b6264bb7124086089e9e69c10c9b6; breaks CI
with error `Concurrent upstream jobs persisted the same file(s) into the workspace:`
PR Close#35857
In some cases, we want to test the AIO app or docs examples against the
locally built Angular packages (for example to ensure that the changes
in a commit do not introduce a breaking change). In order to achieve
this, we have the `ng-packages-installer` script that handles updating
a project's `package.json` file to use the locally built Angular
packages (and appropriate versions for their (dev-/peer-)dependencies).
Previously, `ng-packages-installer` would only consider the locally
built Angular packages (from `dist/packages-dist/`). However, given that
Zone.js is now part of the `angular/angular` repo, it makes sense to
also use the locally built Zone.js package (from `dist/zone.js-dist/`).
Otherwise, the tests might fail for commits that update both the Angular
packages (and related docs examples) and the Zone.js package. An example
of such a simultaneous change (that would have broken tests) is #33838.
This commit updates the script to install the locally built Zone.js
package (in addition to the Angular ones). The commit ensures that the
Zone.js package will always be available alongside the Angular packages
(i.e. that the Zone.js package will be built by the same script that
builds the Angular packages and that the `dist/zone.js-dist/` directory
will be cached on CI).
Note: This problem was discovered while enabling docs examples unit
tests in #34374.
PR Close#35780
Previously, `NgPackagesInstaller` would only look for Angular local
packages and do so by listing all (deeply nested) files in
`dist/packages-dist/` and looking for `package.json` files nested two
levels deep (i.e. `dist/packages-dist/*/package.json`). Thus, it would
unnecessarily check a large number of files.
This commit changes the package detection logic to instead look for
a `package.json` file directly inside each subdirectory of
`dist/packages-dist/`, which speeds up the operation.
It also refactors the code to make it easier to look for packages in
other directories (besides `dist/packages-dist/`). This will be useful
in a subsequent commit to look for and use the locally built `zone.js`
package (from `dist/zone.js-dist/`).
PR Close#35780
This commit moves the build-related scripts
(`build-ivy-npm-packages.js`, `build-packages-dist.js` and
`package-builder.js`) to a dedicated directory to keep the `scripts/`
directory cleaner.
It also moves the logic for building the `zone.js` package to a separate
script, `zone-js-builder.js`, to make it re-usable. A subsequent commit
will use it to build the `zone.js` package when building the Ivy Angular
packages as well.
PR Close#35780
This commit adds a new preprocessor to use `${@searchKeywords}`, allowing
the docs to use a list of custom search phrases that will be
prioritized over the keywords found in the content.
Closes#35449
PR Close#35539
On API docs pages for Angular packages (e.g. https://angular.io/api/common), we show all primary and secondary entry-points. Following a link to one of the secondary entry-points (e.g. https://angular.io/api/common/http), navigates the docs page for the secondary entry-point, where it is incorrectly (and misleadingly) labelled as PACKAGE and not as an entry-point.
Implemented a new ENTRY-POINT label and add support for correctly differentiating between entry-points and packages.
Fixes#34081
PR Close#35427
In #35049, integration and AIO tests were changed to use the browser
provided by `puppeteer` in tests. This commit switches the docs examples
tests to use the same setup.
IMPLEMENTATION NOTE:
The examples are used to create ZIP archives that docs users can
download to experiment with. Since we want the downloaded projects to
resemble an `@angular/cli` generated project, we do not want to affect
the project's Protractor configuration in order to use `puppeteer`.
To achieve this, a second Protractor configuration is created (which is
ignored when creating the ZIP archives) that extends the original one
and passes the approperiate arguments to use the browser provided by
`puppeteer`. This new configuration (`protractor-puppeteer.conf.js`) is
used when running the docs examples tests (on CI or locally during
development).
PR Close#35381
The StackBlitz API (which we use to generate StackBlitz projects on the
fly, when a user clicks on a live example link in the docs) allows
specifying the file to open in the editor by passing a query param. If
no file is specified, StackBlitz opens a default one.
This commit specifies relevant landing files for some of the examples to
make it easier to engage with the examples more quickly, and to see what
the example is attempting to demonstrate.
Fixes#22357.
PR Close#34553
This reverts commit f029af50820765019413fa319330830306b80d6a while we investigate
some failures on master on Circle CI. Currently the Windows tests and the
"test-ivy-aot" jobs are red because of incompatible yarn versions.
PR Close#34402
Adds the ability to expose global symbols in the API docs via the `@globalApi` tag. Also supports optionally setting a namespace which will be added to the name automatically (e.g. `foo` will be renamed to `ng.foo`). Relevant APIs should also be exported through the `global.ts` file which will show up under `core/global`.
PR Close#34237
Rather than bumping up the allowed version of yarn on each release
we should instead just allow for anything within the major version
1 range.
PR Close#34236
The local Angular packages used to build `aio/` when running
`yarn setup-local`/`yarn build-local` (and related commands), are built
by bazel. Bazel, determines the version to use for these locally built
packages based on the latest tag for a commit on the current branch.
(This works as expected during the release, because the packages are
built on the correct branch with up-to-date tags.)
During local development, however, this often leads to generating older
versions than what the current `@angular/cli` version is compatible
with, if the user has not fetched the latest tags from `angular/angular`
or the branch has not been rebased recently.
Previously, the above (common) situation would result in a build error
by the CLI. (Note that this would be a false error, because in this case
the version set by bazel would not reflect the actual version of the
local packages.) The solution would be for the user to fetch the latest
tags from `angular/angular`, rebase their branch and run a bazel build
again (ensuring that it would actually build anew and not emit cached
artifacts). This was cumbersome and most people didn't even know about
it.
This commit avoids this error and the associated pain-points by
overwriting the versions of the installed local packages with fake
versions based on the ones in the lockfile, which are guaranteed to be
compatible with the currently used CLI version.
Fixes#34208
PR Close#34213
Previously, some RxJS-related examples (which are not proper Angular apps) were not
tested on CI as part of the `example-e2e` npm script. This meant that the examples
could get out-of-date or contain compile errors without as noticing.
This commit ensures that the `example-e2e` script picks up these examples and checks
that they compile successfully.
Partly addresses #28017.
PR Close#34063
Previously any code block, which was not marked with
`no-auto-link` css class would have its contents auto-linked to
API pages. Sometimes this results in false positive links being
generated.
This is problematic for triple backticked blocks, which cannot provide
the `no-auto-link` CSS class to prevent the linking.
This commit fixes the problem by allowing the auto-linker to be
configured not to auto-link code blocks that have been marked with an
"ignored" language. By default these are `bash` and `json`.
Triple backticked blocks are able to specify the language directly after
the first set of triple backticks.
Fixes#33859
PR Close#33877
In #33823, `scripts/package-builds.sh` (which is used by both
`build-packages-dist.sh` and `build-ivy-npm-packages.sh`) was updated to
use `realpath`. It turns out that `realpath` does not exist on macOS, so
the build scripts do not work there.
In order to fix this (and also reduce the likelihood of introducing
similar issues in the future), this commit changes these bash scripts to
Node.js scripts (using [ShellJS](https://github.com/shelljs/shelljs) for
a cross-platform implementation of Unix shell commands where necessary).
PR Close#33854
Pete Bacon Darwin
George Kalpakas
Joey Perrott
ajitsinghkaler
Sonu Kapoor
Tony Bove
Greg Magolan
crisbeto
Paul Gschwendtner
Kara Erickson
Igor Minar
JiaLiPassion
Yvonne Allen
Stefanie Fluin
Andrew Scott
Judy Bogart
Kapunahele Wong
dependabot[bot]
arturovt