add more descriptive comments for changes in bazel

Author: annieyw

src/components-examples/BUILD.bazel

@@ -108,6 +108,8 @@ ng_package(
     name = "npm_package",
     srcs = ["package.json"],
     entry_point = ":public-api.ts",
+    // this is a workaround to store a tree artifact in the ng_package.
+    // ng_package does not properly handle tree artifacts currently so we escalate to nested_packages
     nested_packages = [":docs-content"],
     tags = ["docs-package"],
     deps = [":components-examples"] + ALL_EXAMPLES,

tools/highlight-files/highlight-files.ts

@@ -26,11 +26,30 @@ function getBazelActionArguments() {
   return args;
 }
 
+function _detectAndHighlightRegionBlocks(parsed:
+                                           { contents: string, regions: { [p: string]: string } },
+                                         basePath: string,
+                                         outDir: string,
+                                         fileExtension: string) {
+  for (const [regionName, regionSnippet] of Object.entries(parsed.regions)) {
+    // Create files for each found region
+    if (!regionName) {
+      continue;
+    }
+    const highlightedRegion = highlightCodeBlock(regionSnippet, fileExtension);
+    // Convert "my-component-example.ts" into "my-component-example_region-ts.html"
+    const regionBaseOutputPath = basePath.replace(`.${fileExtension}`,
+      `_${regionName}-${fileExtension}.html`);
+    const regionOutputPath = join(outDir, regionBaseOutputPath);
+    ensureDirSync(dirname(regionOutputPath));
+    writeFileSync(regionOutputPath, highlightedRegion);
+  }
+}
+
 if (require.main === module) {
     // The script expects the output directory as first argument. Second is the name of the
     // package where this the highlight target is declared. All remaining arguments will be
     // considered as markdown input files that need to be transformed.
-
     const [outDir, packageName, ...inputFiles] = getBazelActionArguments();
 
     // Walk through each input file and write transformed markdown output
@@ -41,17 +60,7 @@ if (require.main === module) {
         const basePath = relative(packageName, execPath);
         const fileExtension = extname(basePath).substring(1);
         const parsed = regionParser(readFileSync(execPath, 'utf8'), fileExtension);
-        for (const [regionName, regionSnippet] of Object.entries(parsed.regions)) {
-            // Create files for each found region
-            if (!regionName) { continue; }
-            const highlightedRegion = highlightCodeBlock(regionSnippet, fileExtension);
-            // Convert "my-component-example.ts" into "my-component-example_region-ts.html"
-            const regionBaseOutputPath = basePath.replace(`.${fileExtension}`,
-              `_${regionName}-${fileExtension}.html`);
-            const regionOutputPath = join(outDir, regionBaseOutputPath);
-            ensureDirSync(dirname(regionOutputPath));
-            writeFileSync(regionOutputPath, highlightedRegion);
-        }
+        _detectAndHighlightRegionBlocks(parsed, basePath, outDir, fileExtension);
         // Convert "my-component-example.ts" into "my-component-example-ts.html"
         const baseOutputPath = basePath.replace(`.${fileExtension}`, `-${fileExtension}.html`);
         const outputPath = join(outDir, baseOutputPath);

tools/package-docs-content/index.bzl

@@ -10,7 +10,12 @@ def _package_docs_content(ctx):
     # Directory that will contain all grouped input files. This directory will be
     # created relatively to the current target package. For example:
     # "bin/src/components-examples/docs-content/docs-content". The reason we need to
-    # repeat `docs-content` is for
+    # repeat `docs-content` is that the ng_package rule does not properly handle tree
+    # artifacts in data. Instead, we create a tree artifact that can be put into nested_packages.
+    # Nested packages do not preserve the tree artifact name (i.e. the directory name),
+    # so all contents of the docs-content would be put directly into the @angular/components-examples package.
+    # To avoid that, we create another folder like docs-content in the tree artifact that
+    # is preserved as content of the tree artifact.
     output_dir = ctx.actions.declare_directory("%s/%s" % (ctx.attr.name, ctx.attr.name))
 
     # Support passing arguments through a parameter file. This is necessary because on Windows

tools/region-parser/region-matchers/block-c.ts

@@ -1,5 +1,5 @@
 // These kind of comments are used CSS and other languages that do not support inline comments
-module.exports = {
+export const blockC = {
   regionStartMatcher: /^\s*\/\*\s*#docregion\s*(.*)\s*\*\/\s*$/,
   regionEndMatcher: /^\s*\/\*\s*#enddocregion\s*(.*)\s*\*\/\s*$/,
 };

tools/region-parser/region-matchers/html.ts

@@ -1,5 +1,5 @@
 // These kind of comments are used in HTML
-module.exports = {
+export const html = {
   regionStartMatcher: /^\s*<!--\s*#docregion\s*(.*?)\s*(?:-->)?\s*$/,
   regionEndMatcher: /^\s*<!--\s*#enddocregion\s*(.*?)\s*-->\s*$/,
 };

tools/region-parser/region-matchers/inline-c.ts

@@ -1,5 +1,5 @@
 // This comment type is used in C like languages such as JS, TS, Dart, etc
-module.exports = {
+export const inlineC = {
   regionStartMatcher: /^\s*\/\/\s*#docregion\s*(.*)\s*$/,
   regionEndMatcher: /^\s*\/\/\s*#enddocregion\s*(.*)\s*$/,
 };

tools/region-parser/region-parser.ts

@@ -1,12 +1,12 @@
-const blockC = require('./region-matchers/block-c');
-const html = require('./region-matchers/html');
-const inlineC = require('./region-matchers/inline-c');
+import {blockC} from './region-matchers/block-c';
+import {html} from './region-matchers/html';
+import {inlineC} from './region-matchers/inline-c';
 
-export type Region = {lines: string[], open: boolean};
-export type RegionMap = {[regionName: string]: Region};
+export type Region = { lines: string[], open: boolean };
+export type RegionMap = { [regionName: string]: Region };
 
 export function regionParser(contents: string, fileType: string) {
-    return regionParserImpl(contents, fileType);
+  return regionParserImpl(contents, fileType);
 }
 
 /**
@@ -15,113 +15,115 @@ export function regionParser(contents: string, fileType: string) {
  * @returns {contents: string, regions: {[regionName: string]: string}}
  */
 function regionParserImpl(contents: string, fileType: string)
-  : {contents: string, regions: {[regionName: string]: string}} {
-    const regionMatchers: {[fileType: string]: {[region: string]: RegExp}} = {
-        ts: inlineC,
-        js: inlineC,
-        es6: inlineC,
-        html: html,
-        css: blockC,
-        json: inlineC,
-        'json.annotated': inlineC
-    };
-    const regionMatcher = regionMatchers[fileType];
-    const openRegions: string[] = [];
-    const regionMap: RegionMap = {};
+  : { contents: string, regions: { [regionName: string]: string } } {
+  const regionMatchers: { [fileType: string]: { [region: string]: RegExp } } = {
+    ts: inlineC,
+    js: inlineC,
+    es6: inlineC,
+    html: html,
+    css: blockC,
+    json: inlineC,
+    'json.annotated': inlineC
+  };
+  const regionMatcher = regionMatchers[fileType];
+  const openRegions: string[] = [];
+  const regionMap: RegionMap = {};
 
-    if (regionMatcher) {
-        const lines = contents.split(/\r?\n/).filter((line) => {
-            // debugger;
-            const startRegion = line.match(regionMatcher.regionStartMatcher);
-            const endRegion = line.match(regionMatcher.regionEndMatcher);
+  if (regionMatcher) {
+    const lines = contents.split(/\r?\n/).filter((line) => {
+      // debugger;
+      const startRegion = line.match(regionMatcher.regionStartMatcher);
+      const endRegion = line.match(regionMatcher.regionEndMatcher);
 
-            // start region processing
-            if (startRegion) {
-                // open up the specified region
-                const regionNames = getRegionNames(startRegion[1]);
-                if (regionNames.length === 0) {
-                    regionNames.push('');
-                }
-                regionNames.forEach(regionName => {
-                    const region = regionMap[regionName];
-                    if (region) {
-                        if (region.open) {
-                            throw new Error(
-                              `Tried to open a region, named "${regionName}", that is already open`
-                            );
-                        }
-                        region.open = true;
-                    } else {
-                        regionMap[regionName] = {lines: [], open: true};
-                    }
-                    openRegions.push(regionName);
-                });
+      // start region processing
+      if (startRegion) {
+        // open up the specified region
+        const regionNames = getRegionNames(startRegion[1]);
+        if (regionNames.length === 0) {
+          regionNames.push('');
+        }
+        regionNames.forEach(regionName => {
+          const region = regionMap[regionName];
+          if (region) {
+            if (region.open) {
+              throw new Error(
+                `Tried to open a region, named "${regionName}", that is already open`
+              );
+            }
+            region.open = true;
+          } else {
+            regionMap[regionName] = {lines: [], open: true};
+          }
+          openRegions.push(regionName);
+        });
 
-                // end region processing
-            } else if (endRegion) {
-                if (openRegions.length === 0) {
-                    throw new Error('Tried to close a region when none are open');
-                }
-                // close down the specified region (or most recent if no name is given)
-                const regionNames = getRegionNames(endRegion[1]);
-                if (regionNames.length === 0) {
-                    regionNames.push(openRegions[openRegions.length - 1]);
-                }
+        // end region processing
+      } else if (endRegion) {
+        if (openRegions.length === 0) {
+          throw new Error('Tried to close a region when none are open');
+        }
+        // close down the specified region (or most recent if no name is given)
+        const regionNames = getRegionNames(endRegion[1]);
+        if (regionNames.length === 0) {
+          regionNames.push(openRegions[openRegions.length - 1]);
+        }
 
-                regionNames.forEach(regionName => {
-                    const region = regionMap[regionName];
-                    if (!region || !region.open) {
-                        throw new Error(
-                          `Tried to close a region, named "${regionName}", that is not open`);
-                    }
-                    region.open = false;
-                    removeLast(openRegions, regionName);
-                });
+        regionNames.forEach(regionName => {
+          const region = regionMap[regionName];
+          if (!region || !region.open) {
+            throw new Error(
+              `Tried to close a region, named "${regionName}", that is not open`);
+          }
+          region.open = false;
+          removeLast(openRegions, regionName);
+        });
 
-            } else {
-                openRegions.forEach(regionName => regionMap[regionName].lines.push(line));
-                // do not filter out this line from the content
-                return true;
-            }
+      } else {
+        openRegions.forEach(regionName => regionMap[regionName].lines.push(line));
+        // do not filter out this line from the content
+        return true;
+      }
 
-            // this line contained an annotation so let's filter it out
-            return false;
-        });
-        if (!regionMap['']) {
-            regionMap[''] = {lines, open: false};
-        }
-        return {
-            contents: lines.join('\n'),
-            regions: mapObject(regionMap, (regionName: string, region: Region) =>
-              leftAlign(region.lines).join('\n'))
-        };
-    } else {
-        return {contents, regions: {}};
+      // this line contained an annotation so let's filter it out
+      return false;
+    });
+    if (!regionMap['']) {
+      regionMap[''] = {lines, open: false};
     }
+    return {
+      contents: lines.join('\n'),
+      regions: mapObject(regionMap, (regionName: string, region: Region) =>
+        leftAlign(region.lines).join('\n'))
+    };
+  } else {
+    return {contents, regions: {}};
+  }
 }
 
 function mapObject(obj: RegionMap, mapper: (regionName: string, region: Region) => string) {
-    const mappedObj: {[regionName: string]: string} = {};
-    Object.keys(obj).forEach((key: string) => { mappedObj[key] = mapper(key, obj[key]); });
-    return mappedObj;
+  const mappedObj: { [regionName: string]: string } = {};
+  Object.keys(obj).forEach((key: string) => {
+    mappedObj[key] = mapper(key, obj[key]);
+  });
+  return mappedObj;
 }
 
 function getRegionNames(input: string): string[] {
-    return (input.trim() === '') ? [] : input.split(',').map(name => name.trim());
+  return (input.trim() === '') ? [] : input.split(',').map(name => name.trim());
 }
 
 function removeLast(array: string[], item: string) {
-    const index = array.lastIndexOf(item);
-    array.splice(index, 1);
+  const index = array.lastIndexOf(item);
+  array.splice(index, 1);
 }
 
 function leftAlign(lines: string[]): string[] {
-    let indent = Number.MAX_VALUE;
-    lines.forEach(line => {
-        const lineIndent = line.search(/\S/);
-        if (lineIndent !== -1) {
-            indent = Math.min(lineIndent, indent);
-        }
-    });
-    return lines.map(line => line.substr(indent));
+  let indent = Number.MAX_VALUE;
+  lines.forEach(line => {
+    const lineIndent = line.search(/\S/);
+    if (lineIndent !== -1) {
+      indent = Math.min(lineIndent, indent);
+    }
+  });
+  return lines.map(line => line.substr(indent));
 }