Elgato_dark/angular
1
0
Fork 0
mirror of https://github.com/angular/angular synced 2026-05-24 09:28:37 +00:00
Code Issues Projects Releases Packages Wiki Activity Actions
angular/aio/tools/transforms/templates
History
George Kalpakas bdefeb1f11 perf(docs-infra): reduce unnecessary whitespace in API docs (#43435) 
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
2021-09-14 08:29:50 -07:00
..
api perf(docs-infra): reduce unnecessary whitespace in API docs (#43435) 2021-09-14 08:29:50 -07:00
cli docs: update CLI MAN page format (#40038) 2020-12-14 11:31:07 -08:00
error docs: embed the devtools video in the corresponding guide (#42161) 2021-05-20 16:55:16 +00:00
lib build(docs-infra): add sealed markers to classes in API pages (#42807) 2021-08-17 09:23:09 -07:00
content.template.html build(docs-infra): implement @reviewed tag definition (#40582) 2021-01-28 09:04:49 -08:00
data-module.template.js build(aio): move the transforms folder into the tools folder 2017-04-16 22:05:23 +01:00
example-region.template.html build(aio): move the transforms folder into the tools folder 2017-04-16 22:05:23 +01:00
json-doc.template.json build(aio): move the transforms folder into the tools folder 2017-04-16 22:05:23 +01:00
overview-dump.template.html refactor(docs-infra): refactor templates (#24378) 2018-08-31 09:42:10 -07:00
README.md build(docs-infra): remove legacy jsdoc tag processing (#26039) 2018-09-24 09:11:02 -07:00
sitemap.template.xml build(aio): generate sitemap from the generated pages (#21689) 2018-01-22 12:55:15 -08:00

README.md

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 (bread-crumbs, header, embedded contents and body)
    • package.template.html
    • export-base.template.html (short-description, security-notes, deprecation, overview, see-also, details, usageNotes)
      • 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
        • value-module.template.html
      • type-alias.template.html
      • pipe.template.html
      • ngmodule.template.html

Doc Properties

It is useful to know what properties are available on each doc type when working with the templates. The typescript Dgeni package is now written in TypeScript and there is a class for each of the types of API document. See https://github.com/angular/dgeni-packages/tree/master/typescript/src/api-doc-types. This is a good place to go to see what properties you can use in the templates.