Commit Graph

382 Commits

Author SHA1 Message Date
mgechev c9bc88757b docs: embed the devtools video in the corresponding guide (#42161)
Allow people consume the content in a video format.

PR Close #42161
2021-05-20 16:55:16 +00:00
Pete Bacon Darwin d59f2b0d0c refactor(core): remove unnecessary cast (#41960)
The `as any` is no longer needed since `providedIn` can accept `'any'`.

PR Close #41960
2021-05-10 10:28:31 -04:00
Pete Bacon Darwin 71f37c9d9c build(docs-infra): add NgModules references to provided injectables (#41960)
Parse the `providers` property of each NgModule doc and add this doc to
the `ngModules` property of each provided injectable.

PR Close #41960
2021-05-10 10:28:30 -04:00
Pete Bacon Darwin 85f5cb45d2 build(docs-infra): associate `providedIn` injectables with their NgModule (#41960)
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
2021-05-10 10:28:30 -04:00
George Kalpakas 2076bde100 build(docs-infra): take disambiguated doc paths into account when generating the sitemap (#41842)
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
2021-04-27 14:05:23 -07:00
Pete Bacon Darwin 538286df16 build(docs-infra): add path disambiguation (#41788)
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
2021-04-26 12:12:00 -07:00
Pete Bacon Darwin 2ede980fea build(docs-infra): no duplicate docTypes in postProcessHtml processor (#41788)
This processor was being initialized with the same docTypes twice.

PR Close #41788
2021-04-26 12:11:59 -07:00
George Kalpakas 99f2ffc740 build: update stemmer to version 2.0.0 (#41724)
NOTE:
`stemmer` v2.0.0 switched to ES modules (see
words/stemmer@03519229c8), which means
that the only way to consume it in our CommonJS setup (for example, in
[generateKeywords][1]) is via an async `import()`.

This commit makes the `generateKeywords` processor asynchronous in order
to be able to dynamically import and use `stemmer`.

[1]: 251bec159a/aio/tools/transforms/angular-base-package/processors/generateKeywords.js

PR Close #41724
2021-04-26 11:00:59 -07:00
George Kalpakas a938849148 fix(docs-infra): apply custom `autoLinkCode` filters to single-word `<code>` elements (#41709)
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
2021-04-26 10:59:08 -07:00
George Kalpakas de19b8bb88 fix(docs-infra): do not process generated nodes for auto-linking (#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
2021-04-26 10:59:07 -07:00
Pete Bacon Darwin 60d023449b build(docs-infra): ensure that jasmine node tests fail on build error (#41596)
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
2021-04-13 11:54:15 -07:00
Alan Agius ed7d288364 build: update several dependencies (#41434)
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
2021-04-12 16:46:29 -07:00
Pete Bacon Darwin 14a64acb72 build(docs-infra): store search dictionary as a string (#41447)
Previously, the search index info file contained an array of strings that is
the dictionary of terms in the corpus.
Storing this as a space separated string reduces the size of the file.

PR Close #41447
2021-04-07 13:51:08 -07:00
Pete Bacon Darwin 65cd44e731 build(docs-infra): tidy up the generateKeywords processor (#41447)
The recent PR #41368 contained some changes that could be improved.

PR Close #41447
2021-04-07 13:51:08 -07:00
George Kalpakas d42019d412 build(docs-infra): update `eslint` and `eslint-plugin-jasmine` to latest versions (#41429)
This commit updates the `eslint` and `eslint-plugin-jasmine` packages to
latest versions to take advantage of latest fixes and improvements.

PR Close #41429
2021-04-06 10:22:53 -07:00
George Kalpakas 180c1b555f fix(docs-infra): avoid auto-linking generic word `state` (#41438)
Since `state` is a generic word, this commit adds it to the list of
ignored words for auto-linking to avoid incorrectly auto-linking to the
[state()][1] animation helper. For example, see `/ngsw/state` in the
[ServiceWorker in production][2] guide.

[1]: https://v10.angular.io/api/animations/state
[2]: https://v10.angular.io/guide/service-worker-devops#locating-and-analyzing-debugging-information

PR Close #41438
2021-04-05 08:56:43 -07:00
Pete Bacon Darwin fccffc647b refactor(docs-infra): include more info in search index data (#41368)
The AIO search index is built in a WebWorker on the browser from a set
of page information that is downloaded as a JSON file (`search-data.json`).
We want to keep this file as small as possible while providing enough
data to generate a useful index to query against.

Previously, we only included one copy of each (non-ignored) term from each
doc but this prevents more subtle ranking of query results, since the number
of occurences of a term in a doc is lost.

This commit changes the generated file in the following ways:

- All non-ignored terms are now included in the order in which they appear
  in the doc.
- The terms are indexed into a dictonary to avoid the text of the term being
  repeated in every doc that contains the term.
- Each term is pre-"stemmed" using the same Porter Stemming algorith that the
  Lunr search engine uses.

The web-worker has been updated to decode the new format of the file.
Now that all terms are included, it may enable some level of phrase based
matching in the future.

The size of the generated file is considerably larger than previously, but
on production HTTP servers the data is sent compressed, which reduces the
size dramatically.

PR Close #41368
2021-04-01 12:02:37 -07:00
Pete Bacon Darwin fbdb19c263 docs(localize): expose documentation for the `@angular/localize` package (#40317)
PR Close #40317
2021-03-19 12:36:10 -07:00
Pete Bacon Darwin 2893b925c3 build(docs-infra): capture all decorators in doc-gen (#41091)
In 6cff877 we broke the decorator docs because the
doc-gen no longer knew how to identify them.

This commit updates the dgeni processor responsible
for identifying the decorators in the code and ensures
that the docs are now generated correctly.

Fixes #40851

PR Close #41091
2021-03-08 08:34:40 -08:00
Pete Bacon Darwin 8945d7c7c1 build(docs-infra): add a link to `usage notes` from `description` (#40835)
The "Usage Notes" section is often at the bottom of a long page of content
which can make it difficult to discover. This commit adds a link at the
end of the "Description" if there is a "Usage Notes" section on the page.
This link should help the reader to discover that there is more information
available further down the page.

This is basically a marginal fix. The longer term fix should be to
consider what content goes in which sections and how they should
be laid out on the page.

See #40753

PR Close #40835
2021-02-16 07:47:08 -08:00
George Kalpakas 43ecf8a77b feat(platform-server): allow shimming the global env sooner (#40559)
`@angular/platform-server` provides the foundation for rendering an
Angular app on the server. In order to achieve that, it uses a
server-side DOM implementation (currently [domino][1]).

For rendering on the server to work as closely as possible to running
the app on the browser, we need to make DOM globals (such as `Element`,
`HTMLElement`, etc.), which are normally provided by the browser,
available as globals on the server as well.

Currently, `@angular/platform-server` achieves this by extending the
`global` object with the DOM implementation provided by `domino`. This
assignment happens in the [setDomTypes()][2] function, which is
[called in a `PLATFORM_INITIALIZER`][3]. While this works in most cases,
there are some scenarios where the DOM globals are needed sooner (i.e.
before initializing the platform). See, for example, #24551 and #39950
for more details on such issues.

This commit provides a way to solve this problem by exposing a
side-effect-ful entry-point (`@angular/platform-server/init`), that
shims the `global` object with DOM globals. People will be able to
import this entry-point in their server-rendered apps before
bootstrapping the app (for example, in their `main.server.ts` file).
(See also [#39950 (comment)][4].)

In a future update, the [`universal` schematics][5] will include such an
import by default in newly generated projects.

[1]: https://www.npmjs.com/package/domino
[2]: https://github.com/angular/angular/blob/0fc8466f1be392917e0c/packages/platform-server/src/domino_adapter.ts#L17-L21
[3]: https://github.com/angular/angular/blob/0fc8466f1be392917e0c/packages/platform-server/src/server.ts#L33
[4]: https://github.com/angular/angular/issues/39950#issuecomment-747598403
[5]: https://github.com/angular/angular-cli/blob/cc51432661eb4ab4b6a3/packages/schematics/angular/universal

PR Close #40559
2021-02-12 08:55:25 -08:00
George Kalpakas 4e4fcacb6d fix(docs-infra): correctly handle entry-points with no public exports (#40737)
Previously, if an entry-point had no public exports (such as the
`@angular/platform-server/shims` introduced in #40559, which is a
side-effect-ful entry-point), it was incorrectly marked as having all
its exports deprecated (which marks the entry-point as deprecated as
well).

This commit fixes this by ensuring that an entry-point is not marked as
having all its exports deprecated if it has no public exports.

PR Close #40737
2021-02-09 10:56:17 -08:00
Pete Bacon Darwin d4f42b3223 build(docs-infra): implement `@reviewed` tag definition (#40582)
The `@reviewed` tag can be used to specify the date when the
document was last reviewed.

PR Close #40582
2021-01-28 09:04:49 -08:00
Pete Bacon Darwin 9491318c26 build(docs-infra): move docs-watch settings to a base package (#40479)
This new `base-authoring-package` captures all the settings, which
turns of potentially fatal checks, in one place. This new package is
then used as a base for all the docs-watch related packages, rather
than dotting the settings in a variety of different packages. This also
has the benefit that the standard configuration for doc-gen is fatal
on failed checks by default.

PR Close #40479
2021-01-20 16:12:15 -08:00
Pete Bacon Darwin ead9ccd566 build(docs-infra): fail gently if a changed file is unknown (#40479)
When using `docs-watch` we try to match the changed file
to a dgeni package in order to trigger a minimal set of processors.

Previously, if the changed file could not be matched we emitted an
ugly error. Now we provide a helpeful message.

PR Close #40479
2021-01-20 16:12:15 -08:00
Pete Bacon Darwin fb97e67fcb build(docs-infra): fail if there are unused example regions (#40479)
We can define regions in our examples that can be referenced
and rendered in guides as code snippets. It is quite hard to ensure
that these regions are maintained correctly. One reason for this is
it is hard to know whether a region is being used or not.

This commit adds a new processor that checks for unused named
regions in examples and fails if any are found.

Fixes #19761

PR Close #40479
2021-01-20 16:12:15 -08:00
Pete Bacon Darwin 5dd604a15d build(docs-infra): improve docs-watch example matching (#40479)
In the `docs-watch` job we attempt to guess what additional files need
to be processed given a change to a single file. Previously we were not
finding links to examples that were defined over multiple lines. E.g.

```
<code-pane
  header="src/app/app.component.html"
  region="hero-birthday-template"
  path="pipes/src/app/app.component.html">
</code-pane>
```

This commit improves the regular expression to handle these cases.

PR Close #40479
2021-01-20 16:12:15 -08:00
Pete Bacon Darwin c6a2267bb4 build(docs-infra): remove outdated comment (#40479)
The comment referred to pre v9 Angular. The `http` package has
now been completely removed.

PR Close #40479
2021-01-20 16:12:15 -08:00
twerske 3cfb4b4ef9 docs: add embedded videos to error guides (#40453)
add embedded youtube videos
provide visual debugging for top errors

PR Close #40453
2021-01-20 08:47:00 -08:00
twerske fbfd4889a9 build(docs-infra): error guides in docs (#40060)
add /errors to docs
create formatting for error guides infra

PR Close #40060
2021-01-14 11:28:52 -08:00
Pete Bacon Darwin a7a2123ade build(docs-infra): fail if we attempt to autolink to a private doc (#40404)
Previously we only logged a warning if we attempted to auto-link
to a doc that had no `path` property, which implies that it is private
and is not rendered.

Now we fail hard during full doc-gen, although when running the
`yarn serv-and-sync` command it should not fail if changes are
only made to guides, which is what authors who use this tool
are most likely to do.

PR Close #40404
2021-01-13 14:03:05 -08:00
Pete Bacon Darwin 59bcd45930 build(docs-infra): ensure private exported subclasses are not rendered (#40404)
Previously, only the first layer of sub-classes were filtered to remove
private exports. But on recursing down further levels these were not
filtered out.

PR Close #40404
2021-01-13 14:03:04 -08:00
Pete Bacon Darwin 7a7dc89332 build(docs-infra): add `@default` tag-def support (#40404)
This tag-def is being used in the `platform-server` source code,
and was causing warnings in the doc-gen. Adding support
prevents the warning from being shown.
Other than that this change has no effect on the generated
documentation, since the `@default` tag is not used in any
templates.

PR Close #40404
2021-01-13 14:03:04 -08:00
Alan Agius 044cd52996 docs: update CLI MAN page format (#40038)
With this change we update the CLI docs template to seperate
the following the default and value types from the argument field.

This should make it clearer and more understandable

PR Close #40038
2020-12-14 11:31:07 -08:00
Marcono1234 3e1e5a15ba docs: update links to use HTTPS as protocol (#39718)
PR Close #39718
2020-11-20 12:52:16 -08:00
Pete Bacon Darwin e4028ae5c4 build(docs-infra): compute previous version list (#39689)
Previously we hand coded the list of previous major versions
that are displayed in the left navigation.

Now these are generated from the tags in GitHub.

Closes #39688

PR Close #39689
2020-11-18 09:13:20 -08:00
George Kalpakas 35fdc6d92f build(docs-infra): ignore `doc.basePath` when generating keywords for each document (#39409)
The `generateKeywords` dgeni processor automatically generates keywords
for each document by extracting words from each string property of a
`doc` object.

This commit adds `basePath` to the list of ignored properties, so that
it is _not_ considered when generating keywords. `basePath` mostly
contains the path to some root directory (such as
`/home/circleci/ng/packages`) and as such it does not contain useful
keywords.

For example, searching for `circleci` will match all API docs, because
it happens to be in the `basePath`:
https://v10.angular.io/?search=circleci

PR Close #39409
2020-10-26 10:52:00 -07:00
Chellappan dace4aacb6 docs: fix for HttpRequest expansion panel (#39166)
Fixes #39156

PR Close #39166
2020-10-08 09:38:09 -07:00
Pete Bacon Darwin 293270696b build(docs-infra): render optional decorator options with a ? (#39167)
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
2020-10-07 13:33:26 -07:00
George Kalpakas efe0e03fe1 docs(docs-infra): apply the one-sentence-per-line rule to Markdown files in `aio/tools/` (#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
2020-09-30 09:20:00 -04:00
Joey Perrott 93c3d8f9fd fix(platform-webworker): remove platform-webworker and platform-webworker-dynamic (#38846)
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
2020-09-30 09:13:59 -04:00
Joey Perrott ffe89fb07d test(docs-infra): remove usage of blacklist in test naming (#38927)
Remove usage of blacklist in test naming of processor tranform tests.

PR Close #38927
2020-09-23 15:46:02 -04:00
ajitsinghkaler 5b33798796 feat(docs-infra): created new widget for events page (#36517)
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
2020-09-16 15:14:18 -07:00
Sonu Kapoor 0681a20d28 fix(docs-infra): add guard to not render anchor link for private api (#38589)
This commit adds a guard that prevents rendering anchor links for
private api's.

Closes #38564

PR Close #38589
2020-08-26 12:51:04 -07:00
George Kalpakas 0551fbdf88 fix(docs-infra): correctly generate CLI commands docs when the overview page moves (#38365)
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
2020-08-06 11:41:05 -07:00
Joey Perrott d1ea1f4c7f build: update license headers to reference Google LLC (#37205)
Update the license headers throughout the repository to reference Google LLC
rather than Google Inc, for the required license headers.

PR Close #37205
2020-05-26 14:26:58 -04:00
Sonu Kapoor 22d80a6780 refactor(docs-infra): refactors `createOverviewDump` (#37141)
This commit removes the dependency on the `lodash` module and refactors
the `createOverviewDump` method.

PR Close #37141
2020-05-18 10:31:06 -07:00
Sonu Kapoor 89995075e6 refactor(docs-infra): refactors `extractDecoratedClasses` (#37135)
This commit removes the dependency on the `lodash` module and refactors
the `extractDecoratedClasses` method.

PR Close #37135
2020-05-18 10:25:30 -07:00
Sonu Kapoor 03afa36334 refactor(docs-infra): refactors `checkUnbalancedBackTicks` (#37065)
This commit removes the dependency on the `lodash` module and refactors
the `checkUnbalancedBackTicks` method.

PR Close #37065
2020-05-15 10:13:19 -07:00
Pete Bacon Darwin 901db0e730 build(docs-infra): remove `{@searchKeywords}` from content when rendering (#37132)
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
2020-05-15 10:04:45 -07:00