.substr() is deprecated so we replace it with functions which work similarily but aren't deprecated
Signed-off-by: Tobias Speicher <rootcommander@gmail.com>
PR Close#45397
The underlying parser that the CLI uses changed which caused minor changes in the generated JSON helps especially for subcommands.
The folder structure of the Angular CLI repo also changed slightly.
More context: https://github.com/angular/angular-cli/pull/22778
PR Close#45225
This implementation change was originally proposed as part of Typed Forms, and will have major consequences for that project as described in the design doc. Submitting it separately will greatly simplify the risk of landing Typed Forms. This change should have no visible impact on normal users of FormControl.
See the Typed Forms design doc here: https://docs.google.com/document/d/1cWuBE-oo5WLtwkLFxbNTiaVQGNk8ipgbekZcKBeyxxo.
PR Close#44316
PR Close#44806
Recently, the [CLI repository][1] switched to not prefixing tag names
with a `v`. Update the `versionInfo` generated for CLI commands docs, so
that the links to the source code (which include the tag name) are
correct.
Fixes#44822
[1]: https://github.com/angular/angular-cli
PR Close#44835
Refs #42966.
Look for changes in error docs (i.e. docs under `aio/content/error/`) in
`authors-package`, so that such docs are tracked when running the
`serve-and-sync` script.
PR Close#44704
Refs #42966.
Look for changes in error docs (i.e. docs under `aio/content/error/`) in
`authors-package`, so that such docs are tracked when running the
`serve-and-sync` script.
PR Close#44704
This new processor, named `mergeOverriddenImplementation`, allows Dgeni to produce correct documentation for symbols with overridden exported constructors. For example, in the following example, the implementation documentation will be used, including the constructor signature:
```
export const Foo: FooCtor = FooImpl as FooCtor;
```
This is a major improvement over the current situation, in which no constructor signature is documented whatsoever.
PR Close#44689
add 'json' to the ignoreGenericWords set so that it doesn't get
wrongly linked to the jsonPipe during the aio docs generation
as it is a generic javarscript term
PR Close#44294
If there were 1 or 2 additional overloads on a free-standing function in the API the overloads were not being shown.
Also the type of overload parameters were not being escaped correctly.
PR Close#44090
add 'number' to the ignoreGenericWords set so that it doesn't get
wrongly linked to the decimalPipe during the aio docs generation
as it is a generic typescript term
PR Close#44000
Linting has recently been removed from the examples provided in angular.io
(see PRs #43592 and #43746) such removal effects the downloadable and
stackblitz examples but linting is still generally used in the examples
in the aio project itself (they are being migrated from tslint to eslint in
PR #43218) thus eslint directive comments are still necessary in the code itself.
So the comments need to be present but need not to be exposed to the users
(not in the zips, stackblitzes nor docs themselves), these changes are
removing such comments during the examples' parsing phase (effectively
removing them from all three sources mentioned above).
Original discussion: https://github.com/angular/angular/pull/43218#discussion_r697305494resolves#43788
PR Close#43831
This commit updates the necessary config settings to allow `.mjs` files to be able to be parsed by the region parser. We configure the parser to use `inline-c-only` so that comments are generated in like the below
```
// #docregion
```
rather than
```
/* #docregion */
```
PR Close#44027
Fix incorrect escape of special characters when rendering member heritage docs. Example: DefaultIterableDiffer docs incorrectly renders what this class implements - it does not fully display generic types of implemented interfaces.
PR Close#43956
This commit helps to make the section that describes an overview of the syntax of a CLI command stand out from the surrounding text.
Closes#26574
PR Close#43850
In the API docs, concrete classes do not list the "implementation" overload on a method, since this is not strictly part of its API.
We recently fixed the rendering of interfaces to display all the overloads, since there is no "implementation" overload.
This commit also fixes the rendering of "pseudo-classes", which are a combination of an interface
and a constant.
Fixes#43001
PR Close#43734
In the API docs, concrete classes do not list the "implementation" overload on a method, since this is not strictly part of its API.
There is already a special case for abstract methods that do not have such an implementation overload.
But we were missing the case where the method was part of an interface. In interfaces none of the methods have implementation overloads.
Fixes#43001
PR Close#43614
Previously, deprecation notes for deprecated class/interface properties
were not shown in the API docs. This commit fixes it by ensuring that
deprecation notes are shown for properites (similar to how it works for
methods).
PR Close#43566
This change makes docplaster markers fit better with the surrounding code
that is being rendered. Instead of:
```
{
"a": 100,
// ...
"b": 200,
// ...
}
```
you can now get
```
{
"a": 100,
// ...
"b": 200,
// ...
}
```
PR Close#43216
Now JSON files should be commented using
```
// #docregion
```
rather than
```
/* #docregion */
```
There are currently no JSON files with either kind of comments so this change
has no impact yet.
But when we add some examples with such comments, they will also benefit
from `// ... ` style docplasters to join docregion fragments.
PR Close#43216
The HTML for the docs pages is generated by Dgeni based on some
[Nunjucks][1] templates.
Previously, these templates were set up in a way that introduced a lot
excess whitespace in the generated HTML, unnecessarily bloating the
corresponding JSON files that need to be downloaded in order to view a
certain docs page. This has been discussed in #28105 and was again
observed while investigating #43285.
This commit refactors some of the templates related to API docs (which
seem to be the most affected ones) to drastically reduce the amount of
excess whitespace. More specifically, the total size of all files in
`generated/docs/api/` was reduced from ~13MB to ~7MB.
Besides the reduced payload size for each API page, this change will
also reduce the amount of memory needed by the ServiceWorker to cache
the API pages that have been visited by a user.
NOTE:
The affected files are not eagerly downloaded when navigating to
angular.io. Instead, each file is downloaded individually, as soon as a
user visits the corresponding API docs page. Therefore, the impact of
this change will be relatively small for most users.
[1]: https://mozilla.github.io/nunjucks/
PR Close#43435
NOTE:
This [version][1] includes a breaking fix ([commit af59f343d][2]). More
specifically `github-slugger` will no longer trim the text of a heading
before generating an ID and (with whitespace converted to `-`) this
results in different heading IDs:
**Before:** `<h3> foo bar </h3>` --> `<h3 id="foo-bar">...`
**After:** `<h3> foo bar </h3>` --> `<h3 id="--foo-bar--">...`
The different IDs now break some of our anchor-links, becuase
`github-slugger` is used by [rehype-slug][3], which is in turn used by
our [autolinkHeadings][4] dgeni post-processor.
To avoid the issue with broken anchor links, we update the
`renderMethodDetail()` nunjucks macro to omit excess whitespace in
headings.
[1]: https://github.com/Flet/github-slugger/releases/tag/v1.4.0
[2]: af59f343dc
[3]: https://github.com/rehypejs/rehype-slug
[4]: 75a3c778b1/aio/tools/transforms/angular-base-package/post-processors/autolink-headings.js (L3)
PR Close#43435
migrate aio to eslint as tslint has been deprecated, the migration is restricted to the aio app and
its e2e tests and does not include the other tools, for such reason both tslint and codelyzer have not
been removed (to be done in a next PR)
some minor tweaks needed to be applied to the code so that it would adhere to the new ESLinting behaviour
most TSLint rules have been substituted with their ESLint equivalent, with some exceptions:
* [whitespace] does not have an ESLint equivalent (suggested to be handled by prettier)
* [import-spacing] does not have an ESLint equivalent (suggested to be handled by prettier)
* [ban] replaced with [no-restricted-syntax] as there is no (official/included) ESLint equivalent
some rules have minor different behaviours compared to their TSLint counterparts:
* @typescript-eslint/naming-convention:
- typescript-eslint does not enforce uppercase for const only.
* @typescript-eslint/no-unused-expressions:
- The TSLint optional config "allow-new" is the default ESLint behavior and will no longer be ignored.
* arrow-body-style:
- ESLint will throw an error if the function body is multiline yet has a one-line return on it.
* eqeqeq:
- Option "smart" allows for comparing two literal values, evaluating the value of typeof and null comparisons.
* no-console:
- Custom console methods, if they exist, will no longer be allowed.
* no-invalid-this:
- Functions in methods will no longer be ignored.
* no-underscore-dangle:
- Leading and trailing underscores (_) on identifiers will now be ignored.
* prefer-arrow/prefer-arrow-functions:
- ESLint does not support allowing standalone function declarations.
- ESLint does not support allowing named functions defined with the function keyword.
* space-before-function-paren:
- Option "constructor" is not supported by ESLint.
- Option "method" is not supported by ESLint.
additional notes:
* the current typescript version used by the aio app is 4.3.5, which is not supported by typescript-eslint (the supported
versions are >=3.3.1 and <4.3.0). this causes a warning message to appear during linting, this issue should
likely/hopefully disappear in the future as typescript-eslint catches up
* The new "no-console" rule is not completely equivalent to what we had prior the migration, this is because TSLint's "no-console"
rule let you specify the methods you did not want to allow, whilst ESLint's "no-console" lets you specify the methods that you do
want to allow, so and in order not to have a very long list of methods in the ESLint rule it's been decided for the time being
to simply only allow the "log", "warn" and "error" methods
* 4 dependencies have been added as they have been considered necessary (see: https://github.com/angular/angular/pull/42820#discussion_r669978232)
extra:
* the migration has been performed by following: https://github.com/angular-eslint/angular-eslint#migrating-an-angular-cli-project-from-codelyzer-and-tslin
* more on typescript-eslint at: https://github.com/typescript-eslint/typescript-eslint
PR Close#42820
improve the @usageNotes message by adding the word "is"
(outcome: "Further information is available in...", compared to
"Further information available in...")
PR Close#42888
In #41788, the `disambiguateDocsPathsProcessor` was introduced to fix
an issue with case-insensitively equal paths. This processor may alter
the output paths of some docs. Due to its nature, the
`disambiguateDocPathsProcessor` must be the last processor in the
pipeline that updates a doc's output path. However, the
`updateGlobalApiPathProcess` (which also alters the output paths of some
docs) was not configured to run before `disambiguateDocPathsProcessor`.
As a result, the changes made by `disambiguateDocPathsProcessor` were
overridden by `updateGlobalApiPathProcess`, resulting in the app's
failing to load such global API docs pages. An example of such an API
page is: https://angular.io/api/core/global/ngApplyChanges
This commit fixes it by ensuring that the `updateGlobalApiPathProcess`
is explicitly run before the `disambiguateDocPathsProcessor`, so that
the former does not override the changes made by the latter.
PR Close#42648
To avoid having content files that have the same file path on case-insensitive
file-systems, we now encode the paths to remove uppercase characters.
PR Close#42414
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
Such injectables were not appearing in the providers lists of their NgModule.
This commit updates the doc-gen to support associating these automatically.
Further, it also allows developers to mark other injectables that are provided
in an NgModule with a reference to the NgModule where they are provided.
The commit also does a refactoring of the `processNgModuleDocs` dgeni
processor code, to make it easier to maintain.
Fixes#41203
PR Close#41960
In ##41788, the `disambiguateDocsPathsProcessor` was introduced to fix
an issue with case-insensitively equal paths. This processor may alter
the paths of some docs and thus their final URL in the app.
Previously, both the `disambiguateDocPathsProcessor` and the
`createSitemap` processor (which relies on the docs' computed paths to
generate the sitemap file) were configured to run before the
"rendering-docs" phase. However, this resulted in the
`disambiguateDocPathsProcessor`'s running after `createSitemap`, which
meant that the sitemap did not include the updated doc paths.
This commit fixes it by ensuring that the
`disambiguateDocPathsProcessor` is explicitly run before the
`createSitemap` processor, so that the latter will be able to take into
account any changes made by the former.
PR Close#41842
When two documents have the same `outputPath`, only differing by
letter casing, there can be problems on case-insensitive file-systems:
Only one of each of the docs would end up being written.
Moreover, the Webpack 5 bundler will error if it comes across files
that have this kind of ambiguous paths.
This commit adds a new docType: `disambiguator`, which will display
a list of the docs that match an ambiguous path. Each of the ambiguous
docs is then given a unique path and outputPath to ensure there are no
collisions.
PR Close#41788
Previously, the `autoLinkCode` Dgeni post-processor would not apply the
custom filters when matching the whole contents of a `<code>` element.
This meant that custom filters would not be applied to single-word
`<code>` elements.
You can see occurrences of this issue in the following sections of the
"Reactive forms" guide:
- [Creating nested form groups][1]
(look for `street, city, state, and zip controls`)
- [Using the FormBuilder service to generate controls][2]
(look for `group method`)
This commit fixes this by also applying the custom filters when
processing the whole contents of a `<code>` element.
This commit also updates the `filterPipes` custom filter to allow
matching a pipe's name in a single-word `<code>` element (where there is
no preceeding `|` character).
[1]: https://v10.angular.io/guide/reactive-forms#creating-nested-form-groups
[2]: https://v10.angular.io/guide/reactive-forms#using-the-formbuilder-service-to-generate-controls
PR Close#41709
While generating the docs, when a `<code>` element is inspected for
auto-linking, the `autoLinkCode` Dgeni post-processor will break its
contents up into words and generate text nodes for those words that
should not be auto-linked.
Previously, our text node visitor would visit these generated text nodes
and try to auto-link them too. As a result, it would unnecessarily
process nodes that had already been checked (and could potentially
generate links that would otherwise be ignored).
You can see an occurrence of this issue in the
[Create the product list][1] section of the
"Getting started with Angular" tutorial (look for `<a>`).
This commit fixes this by ensuring the visitor will skip the current
node and any nodes generated by `autoLinkCode`.
[1]: https://v11.angular.io/start#create-the-product-list
PR Close#41709
Previously if there was a problem when building the tests, the error would
be swallowed as an unhandled promise rejection. Now these are caught and
the process is exited with a non-zero value to prevent any CI jobs from
passing incorrectly.
PR Close#41596
With this change we update several dependencies to avoid Renovate creating a lot of PRs during onboarding. We also remove yarn workspaces as after further analysis these are not needed.
Certain dependencies such as `@octokit/rest`, `remark` and `@babel/*` have not been updated as they require a decent amount of work to update, and it's best to leave them for a seperate PR.
PR Close#41434
