build(bazel): add bazel targets for aio doc generation

This is an incremental step to produce dgeni output with bazel. The generated outputs are not yet used by other targets.
2026-09-14 13:54:52 +08:00 · 2022-03-15 15:32:44 -07:00
parent 4f03a9c327
commit 431c562815
66 changed files with 697 additions and 56 deletions
@@ -114,3 +114,48 @@ architect_test(
    configuration_env_vars = ["NG_BUILD_CACHE"],
    data = TEST_FILES + TEST_DEPS,
 )
+
+# External deps required by dgeni transforms
+DGENI_DEPS = [
+    "@aio_npm//css-selector-parser",
+    "@aio_npm//dgeni-packages",
+    "@aio_npm//entities",
+    "@aio_npm//fs-extra",
+    "@aio_npm//hast-util-is-element",
+    "@aio_npm//hast-util-to-string",
+    "@aio_npm//ignore",
+    "@aio_npm//image-size",
+    "@aio_npm//json5",
+    "@aio_npm//rehype-slug",
+    "@aio_npm//remark",
+    "@aio_npm//remark-html",
+    "@aio_npm//rxjs",
+    "@aio_npm//semver",
+    "@aio_npm//stemmer",
+    "@aio_npm//unist-util-filter",
+    "@aio_npm//unist-util-source",
+]
+
+# All transforms and sources needed by dgeni to produce docs
+DGENI_FILES = glob([
+    "content/**",
+    "src/assets/**",
+    "tools/transforms/**",
+]) + [
+    "@angular_cli_src//:files_for_docgen",  # Downloaded cli snapshot (see WORKSPACE)
+    "//:package.json",
+    "//packages:files_for_docgen",
+]
+
+# Run dgeni generation
+npm_package_bin(
+    name = "dgeni",
+    args = ["./aio/tools/transforms/angular.io-package"],
+    configuration_env_vars = ["PATH"],  # Need PATH for dgeni package that invokes git
+    data = DGENI_FILES + DGENI_DEPS,
+    env = {
+        "BAZEL_DGENI_OUTPUT_PATH": "$(@D)",
+    },
+    output_dir = True,
+    tool = "@aio_npm//dgeni/bin:dgeni",
+)
@@ -1,3 +0,0 @@
-/node_modules
-package.json
-yarn.lock
@@ -115,6 +115,7 @@
    "@angular/compiler-cli": "15.0.0-rc.0",
    "@bazel/bazelisk": "^1.7.5",
    "@types/jasmine": "~4.3.0",
+    "@bazel/typescript": "4.6.2",
    "@types/lunr": "^2.3.3",
    "@types/node": "^12.7.9",
    "@types/trusted-types": "^2.0.2",
@@ -21,7 +21,7 @@ const linksPackage = require('../links-package');
 const remarkPackage = require('../remark-package');
 const targetPackage = require('../target-package');

-const { PROJECT_ROOT, CONTENTS_PATH, OUTPUT_PATH, DOCS_OUTPUT_PATH, TEMPLATES_PATH, AIO_PATH, requireFolder } = require('../config');
+const { BAZEL_OUTPUT_PATH, PROJECT_ROOT, CONTENTS_PATH, OUTPUT_PATH, DOCS_OUTPUT_PATH, TEMPLATES_PATH, AIO_PATH, requireFolder } = require('../config');

 module.exports = new Package('angular-base', [
  gitPackage, jsdocPackage, nunjucksPackage, linksPackage, examplesPackage, targetPackage, remarkPackage, postProcessPackage
@@ -136,7 +136,8 @@ module.exports = new Package('angular-base', [
    //  That being said do this only add 500ms onto the ~30sec doc-gen run - so not a huge issue)
    checkAnchorLinksProcessor.ignoredLinks.push({
      test(url) {
-        return (existsSync(resolve(SRC_PATH, url)));
+        // Some links point to assets in the source tree while others point to the generated bazel output
+        return existsSync(resolve(SRC_PATH, url)) || existsSync(resolve(BAZEL_OUTPUT_PATH, url));
      }
    });
    checkAnchorLinksProcessor.pathVariants = ['', '/', '.html', '/index.html', '#top-of-page'];
@@ -154,9 +155,12 @@ module.exports = new Package('angular-base', [
    ];
  })

-
  .config(function(postProcessHtml, addImageDimensions, autoLinkCode, filterPipes, filterAmbiguousDirectiveAliases, ignoreHttpInUrls, ignoreGenericWords) {
-    addImageDimensions.basePath = path.resolve(AIO_PATH, 'src');
+    // Some images exist within the source tree while others are in the generated bazel output
+    addImageDimensions.basePaths = [
+      path.resolve(AIO_PATH, 'src'),
+      BAZEL_OUTPUT_PATH,
+    ];
    autoLinkCode.customFilters = [ignoreGenericWords, ignoreHttpInUrls, filterPipes, filterAmbiguousDirectiveAliases];
    autoLinkCode.failOnMissingDocPath = true;
    postProcessHtml.plugins = [
@@ -27,7 +27,7 @@ module.exports = function addImageDimensions(getImageDimensions) {
        }

        try {
-          const dimensions = getImageDimensions(addImageDimensionsImpl.basePath, src);
+          const dimensions = getImageDimensions(addImageDimensionsImpl.basePaths, src);
          if (props.width === undefined && props.height === undefined) {
            props.width = '' + dimensions.width;
            props.height = '' + dimensions.height;
@@ -11,7 +11,7 @@ describe('addImageDimensions post-processor', () => {
    const injector = dgeni.configureInjector();
    log = injector.get('log');
    addImageDimensions = injector.get('addImageDimensions');
-    addImageDimensions.basePath = 'base/path';
+    addImageDimensions.basePaths = ['base/path'];
    getImageDimensionsSpy = injector.get('getImageDimensions');
    processor = injector.get('postProcessHtml');
    processor.docTypes = ['a'];
@@ -30,8 +30,8 @@ describe('addImageDimensions post-processor', () => {
      `
    }];
    processor.$process(docs);
-    expect(getImageDimensionsSpy).toHaveBeenCalledWith('base/path', 'a/b.jpg');
-    expect(getImageDimensionsSpy).toHaveBeenCalledWith('base/path', 'c/d.png');
+    expect(getImageDimensionsSpy).toHaveBeenCalledWith(['base/path'], 'a/b.jpg');
+    expect(getImageDimensionsSpy).toHaveBeenCalledWith(['base/path'], 'c/d.png');
    expect(docs).toEqual([jasmine.objectContaining({
      docType: 'a',
      renderedContent: `
@@ -69,7 +69,7 @@ describe('addImageDimensions post-processor', () => {
      renderedContent: '<img src="missing">'
    }];
    expect(() => processor.$process(docs)).toThrowError('Unable to load src in image tag `<img src="missing">` - doc (a) ');
-    expect(getImageDimensionsSpy).toHaveBeenCalledWith('base/path', 'missing');
+    expect(getImageDimensionsSpy).toHaveBeenCalledWith(['base/path'], 'missing');
  });

  it('should ignore images with width or height attributes', () => {
@@ -99,6 +99,6 @@ describe('addImageDimensions post-processor', () => {
    };
    // eslint-disable-next-line jasmine/no-unsafe-spy
    return jasmine.createSpy('getImageDimensions')
-      .and.callFake((base, url) => imageInfo[url]);
+      .and.callFake((basePaths, url) => imageInfo[url]);
  }
 });
@@ -2,5 +2,18 @@ const { join } = require('canonical-path');
 const sizeOf = require('image-size');

 module.exports = function getImageDimensions() {
-  return (basePath, path) => sizeOf(join(basePath, path));
+  return (basePaths, path) => {
+    let error;
+    for (const basePath of basePaths) {
+      try {
+        return sizeOf(resolve(basePath, path));
+      } catch (e) {
+        // Fall back to next basePath if not found
+        error = e;
+      }
+    }
+    if (error) {
+      throw error;
+    }
+  };
 };
@@ -4,8 +4,8 @@ const Package = require('dgeni').Package;
 const basePackage = require('../angular-base-package');
 const contentPackage = require('../content-package');
 const {CONTENTS_PATH, TEMPLATES_PATH, requireFolder} = require('../config');
-const CLI_SOURCE_ROOT = resolve(CONTENTS_PATH, 'cli-src');
-const CLI_SOURCE_PATH = resolve(CLI_SOURCE_ROOT, 'node_modules/@angular/cli');
+
+const CLI_SOURCE_PATH = resolve('external/angular_cli_src');
 const CLI_SOURCE_HELP_PATH = resolve(CLI_SOURCE_PATH, 'help');

 // Define the dgeni package for generating the docs
@@ -1,6 +1,7 @@
 const { resolve } = require('path');
 const { readdirSync } = require('fs');

+const BAZEL_OUTPUT_PATH = process.env.BAZEL_DGENI_OUTPUT_PATH;
 const PROJECT_ROOT = resolve(__dirname, '../../..');
 const AIO_PATH = resolve(PROJECT_ROOT, 'aio');
 const TEMPLATES_PATH = resolve(AIO_PATH, 'tools/transforms/templates');
@@ -8,7 +9,7 @@ const API_TEMPLATES_PATH = resolve(TEMPLATES_PATH, 'api');
 const CONTENTS_PATH = resolve(AIO_PATH, 'content');
 const GUIDE_EXAMPLES_PATH = resolve(CONTENTS_PATH, 'examples');
 const SRC_PATH = resolve(AIO_PATH, 'src');
-const OUTPUT_PATH = resolve(SRC_PATH, 'generated');
+const OUTPUT_PATH = resolve(BAZEL_OUTPUT_PATH, 'generated');
 const DOCS_OUTPUT_PATH = resolve(OUTPUT_PATH, 'docs');
 const API_SOURCE_PATH = resolve(PROJECT_ROOT, 'packages');

@@ -18,6 +19,5 @@ function requireFolder(dirname, folderPath) {
    .filter(p => !/[._]spec\.js$/.test(p))  // ignore spec files
    .map(p => require(resolve(absolutePath, p)));
 }
-
-module.exports = { PROJECT_ROOT, AIO_PATH, TEMPLATES_PATH, API_TEMPLATES_PATH, CONTENTS_PATH, GUIDE_EXAMPLES_PATH, SRC_PATH, OUTPUT_PATH, DOCS_OUTPUT_PATH, API_SOURCE_PATH, requireFolder };
+module.exports = { BAZEL_OUTPUT_PATH, PROJECT_ROOT, AIO_PATH, TEMPLATES_PATH, API_TEMPLATES_PATH, CONTENTS_PATH, GUIDE_EXAMPLES_PATH, SRC_PATH, OUTPUT_PATH, DOCS_OUTPUT_PATH, API_SOURCE_PATH, requireFolder };

@@ -1502,6 +1502,24 @@
  resolved "https://registry.yarnpkg.com/@bazel/bazelisk/-/bazelisk-1.12.0.tgz#f08aebbf4afcb12684422450b0845dd6ef5cfe50"
  integrity sha512-7oQusq1e4AIyFgotxVV7Pc40Et0QyvoVjujL+7/qV5Vrbfh0Nj3CfqSgl63weEyI4r0+K6RlGVsjfRuBi05p5w==

+"@bazel/typescript@4.6.2":
+  version "4.6.2"
+  resolved "https://registry.yarnpkg.com/@bazel/typescript/-/typescript-4.6.2.tgz#9f07b6f8cfb6b0a0e228e5971de412911c910a90"
+  integrity sha512-AUF7kq82bP6DX9Brihr/eQqvNccxVfSXosFxt80h94og5cmMyoc/euXha6rxlOBP3yWXmSo+/qjzO7o8PWJduQ==
+  dependencies:
+    "@bazel/worker" "4.6.2"
+    protobufjs "6.8.8"
+    semver "5.6.0"
+    source-map-support "0.5.9"
+    tsutils "3.21.0"
+
+"@bazel/worker@4.6.2":
+  version "4.6.2"
+  resolved "https://registry.yarnpkg.com/@bazel/worker/-/worker-4.6.2.tgz#0bd105344533335327c2edfa3fc65b04c39cdea8"
+  integrity sha512-DLpN6iQAH6uiUraAs4CESyqs60u55fcKmYgOOVObGuLSQQuX49Lw7XRIN90NibRPwpbBDQichWE3zfra0yKTTw==
+  dependencies:
+    google-protobuf "^3.6.1"
+
 "@colors/colors@1.5.0":
  version "1.5.0"
  resolved "https://registry.yarnpkg.com/@colors/colors/-/colors-1.5.0.tgz#bb504579c1cae923e6576a4f5da43d25f97bdbd9"
@@ -2178,6 +2196,11 @@
  resolved "https://registry.yarnpkg.com/@types/node/-/node-18.0.3.tgz#463fc47f13ec0688a33aec75d078a0541a447199"
  integrity sha512-HzNRZtp4eepNitP+BD6k2L6DROIDG4Q0fm4x+dwfsr6LGmROENnok75VGw40628xf+iR24WeMFcHuuBDUAzzsQ==

+"@types/node@^10.1.0":
+  version "10.17.60"
+  resolved "https://registry.yarnpkg.com/@types/node/-/node-10.17.60.tgz#35f3d6213daed95da7f0f73e75bcc6980e90597b"
+  integrity sha512-F0KIgDJfy2nA3zMLmWGKxcH2ZVEtCZXHHdOQs2gSaQ27+lNeEfGxzkIw90aXswATX7AZ33tahPbzy6KAfUreVw==
+
 "@types/node@^12.7.9":
  version "12.20.55"
  resolved "https://registry.yarnpkg.com/@types/node/-/node-12.20.55.tgz#c329cbd434c42164f846b909bd6f85b5537f6240"
@@ -6315,6 +6338,11 @@ google-p12-pem@^4.0.0:
  dependencies:
    node-forge "^1.3.1"

+google-protobuf@^3.6.1:
+  version "3.21.2"
+  resolved "https://registry.yarnpkg.com/google-protobuf/-/google-protobuf-3.21.2.tgz#4580a2bea8bbb291ee579d1fefb14d6fa3070ea4"
+  integrity sha512-3MSOYFO5U9mPGikIYCzK0SaThypfGgS6bHqrUGXG3DPHCrb+txNqeEcns1W0lkGfk0rCyNXm7xB9rMxnCiZOoA==
+
 got@^9.6.0:
  version "9.6.0"
  resolved "https://registry.yarnpkg.com/got/-/got-9.6.0.tgz#edf45e7d67f99545705de1f7bbeeeb121765ed85"
@@ -9700,6 +9728,25 @@ protobufjs@6.11.3, protobufjs@^6.11.3:
    "@types/node" ">=13.7.0"
    long "^4.0.0"

+protobufjs@6.8.8:
+  version "6.8.8"
+  resolved "https://registry.yarnpkg.com/protobufjs/-/protobufjs-6.8.8.tgz#c8b4f1282fd7a90e6f5b109ed11c84af82908e7c"
+  integrity sha512-AAmHtD5pXgZfi7GMpllpO3q1Xw1OYldr+dMUlAnffGTAhqkg72WdmSY71uKBF/JuyiKs8psYbtKrhi0ASCD8qw==
+  dependencies:
+    "@protobufjs/aspromise" "^1.1.2"
+    "@protobufjs/base64" "^1.1.2"
+    "@protobufjs/codegen" "^2.0.4"
+    "@protobufjs/eventemitter" "^1.1.0"
+    "@protobufjs/fetch" "^1.1.0"
+    "@protobufjs/float" "^1.0.2"
+    "@protobufjs/inquire" "^1.1.0"
+    "@protobufjs/path" "^1.1.2"
+    "@protobufjs/pool" "^1.1.0"
+    "@protobufjs/utf8" "^1.1.0"
+    "@types/long" "^4.0.0"
+    "@types/node" "^10.1.0"
+    long "^4.0.0"
+
 protractor@~7.0.0:
  version "7.0.0"
  resolved "https://registry.yarnpkg.com/protractor/-/protractor-7.0.0.tgz#c3e263608bd72e2c2dc802b11a772711a4792d03"
@@ -10546,6 +10593,11 @@ semver-dsl@^1.0.1:
  resolved "https://registry.yarnpkg.com/semver/-/semver-5.7.1.tgz#a954f931aeba508d307bbf069eff0c01c96116f7"
  integrity sha512-sauaDf/PZdVgrLTNYHRtpXa1iRiKcaebiKQ1BJdpQlWH2lCvexQdX55snPFyK7QzpudqbCI0qXFfOasHdyNDGQ==

+semver@5.6.0:
+  version "5.6.0"
+  resolved "https://registry.yarnpkg.com/semver/-/semver-5.6.0.tgz#7e74256fbaa49c75aa7c7a205cc22799cac80004"
+  integrity sha512-RS9R6R35NYgQn++fkDWaOmqGoj4Ek9gGs+DPxNUZKuwE183xjJroKvyo1IzVFeXvUrvmALy6FWD5xrdJT25gMg==
+
 semver@7.3.4:
  version "7.3.4"
  resolved "https://registry.yarnpkg.com/semver/-/semver-7.3.4.tgz#27aaa7d2e4ca76452f98d3add093a72c943edc97"
@@ -10849,6 +10901,14 @@ source-map-support@0.5.21, source-map-support@^0.5.5, source-map-support@~0.5.20
    buffer-from "^1.0.0"
    source-map "^0.6.0"

+source-map-support@0.5.9:
+  version "0.5.9"
+  resolved "https://registry.yarnpkg.com/source-map-support/-/source-map-support-0.5.9.tgz#41bc953b2534267ea2d605bccfa7bfa3111ced5f"
+  integrity sha512-gR6Rw4MvUlYy83vP0vxoVNzM6t8MUXqNuRsuBmBHQDu1Fh6X015FrLdgoDKcNdkwGubozq0P4N0Q37UyFVr1EA==
+  dependencies:
+    buffer-from "^1.0.0"
+    source-map "^0.6.0"
+
 source-map-support@~0.4.0:
  version "0.4.18"
  resolved "https://registry.yarnpkg.com/source-map-support/-/source-map-support-0.4.18.tgz#0286a6de8be42641338594e97ccea75f0a2c585f"
@@ -11578,6 +11638,13 @@ tslint@~6.1.3:
    tslib "^1.13.0"
    tsutils "^2.29.0"

+tsutils@3.21.0, tsutils@^3.21.0:
+  version "3.21.0"
+  resolved "https://registry.yarnpkg.com/tsutils/-/tsutils-3.21.0.tgz#b48717d394cea6c1e096983eed58e9d61715b623"
+  integrity sha512-mHKK3iUXL+3UF6xL5k0PEhKRUBKPBCv/+RkEOpjRWxxx27KKRBmmA60A9pgOUvMi8GKhRMPEmjBRPzs2W7O1OA==
+  dependencies:
+    tslib "^1.8.1"
+
 tsutils@^2.29.0:
  version "2.29.0"
  resolved "https://registry.yarnpkg.com/tsutils/-/tsutils-2.29.0.tgz#32b488501467acbedd4b85498673a0812aca0b99"
@@ -11585,13 +11652,6 @@ tsutils@^2.29.0:
  dependencies:
    tslib "^1.8.1"

-tsutils@^3.21.0:
-  version "3.21.0"
-  resolved "https://registry.yarnpkg.com/tsutils/-/tsutils-3.21.0.tgz#b48717d394cea6c1e096983eed58e9d61715b623"
-  integrity sha512-mHKK3iUXL+3UF6xL5k0PEhKRUBKPBCv/+RkEOpjRWxxx27KKRBmmA60A9pgOUvMi8GKhRMPEmjBRPzs2W7O1OA==
-  dependencies:
-    tslib "^1.8.1"
-
 tunnel-agent@^0.6.0:
  version "0.6.0"
  resolved "https://registry.yarnpkg.com/tunnel-agent/-/tunnel-agent-0.6.0.tgz#27a5dea06b36b04a0a9966774b290868f0fc40fd"