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
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
Now, one can add an `@alias` tag to API docs, which tells dgeni that this
API element (usually a `const`) is really just an alias for some API element
defined elsewhere.
Dgeni will then look up this API element and copy over the properties from
the alias to the current doc.
For example, we would like to privately export an Enum from `@angular/core`
but then publicly export this from `@angular/common`:
**packages/core/private_exports.ts**
```ts
/**
* Description of this document.
*/
export enum ɵSomeEnum { ... }
```
**packages/common/public_api.ts**
```ts
import {ɵSomeEnum} from '@angular/core';
/**
* @alias core/ɵSomeEnum
*/
export const SomeEnum = ɵSomeEnum;
```
In the generated docs there will be a page for `common/SomeEnum`, which
will be rendered as an enum, rather than a const, showing the description
extracted from the `core/ɵSomeEnum`.
---
The implementation of this feature required some refactoring of the other
processing:
1. Previously `ɵ` prefixed exports were not even considered.
2. Due to 1. some processors needed to have guards added to ignore such
private exports (`addMetadataAliases` and `checkContentRules`).
3. The processing of package pages had to be reworked (and split) so that
it picked up the aliased export docs after their alias proeprties had
been copied.
See FW-1207, FW-632, #29249
PR Close#29673
Includes:
* display ToC for API docs
* update dgeni-packages to 0.24.1
* add floating sidebar in API docs
* add breadcrumbs and structured data for Google crawler
* improved rendering of method overloads
* properties rendered in a table
* params rendered with docs
* removal of outdated "infobox" from all API docs
PR Close#21874
For classes, the tree of subclasses is rendered, recursively.
For interfaces, the descendants are separated into child interfaces, which
extend the interface, and classes, which implement the interface.
Closes#19306
