build(bazel): replace ignore example feature with bazel equivalent

Comment out the entry in the EXAMPLES map to ignore an example.

aio/content/examples/examples.bzl

@@ -11,6 +11,7 @@ load("@aspect_bazel_lib//lib:copy_to_directory.bzl", "copy_to_directory")
 # found in the example. Set "zip" to True to generate archives for any stackblitz or
 # zipper configuration file found in the example.
 #
+# To ignore an example, comment out its row.
 
 EXAMPLES = {
     "accessibility": {"stackblitz": True, "zip": True},
@@ -102,7 +103,9 @@ def docs_example(name):
         name: name of the example
     """
     if name not in EXAMPLES:
-        fail("Cannot find example %s in the EXAMPLES map in aio/content/examples/examples.bzl. Did you forget to add an entry?" % name)
+        # buildifier: disable=print
+        print("WARNING: Example '%s' is being ignored. To include it, add an entry to the EXAMPLES map in aio/content/examples/examples.bzl." % name)
+        return
 
     native.filegroup(
         name = "files",

aio/content/guide/docs-style-guide.md

@@ -328,10 +328,6 @@ Following convention, set the `header` attribute to the file's location within t
 
 Unless otherwise commented, all code snippets in this page are from sample source code located in the `content/examples/docs-style-guide` directory.
 
-<div class="alert is-important">
-
-The documentation tooling reports an error if the file identified in the path does not exist or is in the [`.git-ignore` file](https://github.com/angular/angular/blob/main/aio/content/examples/.gitignore).
-
 <a id="region"></a>
 
 ### Displaying part of a code file

aio/tools/examples/create-example.js

@@ -87,12 +87,11 @@ function writeStackBlitzFile(exampleName, examplePath) {
 }
 
 /**
- * Copy all the files from the `sourcePath`, which are not ignored by the `.gitignore` file in the
- * `EXAMPLES_BASE_PATH`, to the `examplePath`.
+ * Copy all the files from the `sourcePath` to the `examplePath`, except for files
+ * ignored by the source example.
  */
 function copyExampleFiles(sourcePath, examplePath, exampleName) {
   const gitIgnoreSource = getGitIgnore(sourcePath);
-  const gitIgnoreExamples = getGitIgnore(EXAMPLES_BASE_PATH);
 
   // Grab the files in the source folder and filter them based on the gitignore rules.
   const sourceFiles =
@@ -106,8 +105,6 @@ function copyExampleFiles(sourcePath, examplePath, exampleName) {
           .filter(filePath => !/\/$/.test(filePath))
           // Filter out files that match the source directory .gitignore rules
           .filter(filePath => !gitIgnoreSource.ignores(filePath))
-          // Filter out files that match the examples directory .gitignore rules
-          .filter(filePath => !gitIgnoreExamples.ignores(path.join(exampleName, filePath)));
 
   for (const sourceFile of sourceFiles) {
     console.log(' - ', sourceFile);

aio/tools/examples/create-example.spec.js

@@ -2,7 +2,7 @@ const path = require('canonical-path');
 const fs = require('fs-extra');
 const {glob} = require('glob');
 
-const {EXAMPLES_BASE_PATH, EXAMPLE_CONFIG_FILENAME, STACKBLITZ_CONFIG_FILENAME} =
+const {EXAMPLE_CONFIG_FILENAME, STACKBLITZ_CONFIG_FILENAME} =
     require('./constants');
 
 const {
@@ -82,15 +82,12 @@ describe('create-example tool', () => {
 
   describe('copyExampleFiles', () => {
     it('should copy over files that are not ignored by git', () => {
-      const examplesGitIgnorePath = path.resolve(EXAMPLES_BASE_PATH, '.gitignore');
       const sourceGitIgnorePath = path.resolve('/source/path', '.gitignore');
 
       spyOn(console, 'log');
       spyOn(fs, 'existsSync').and.returnValue(true);
       const readFileSyncSpy = spyOn(fs, 'readFileSync').and.callFake(p => {
         switch (p) {
-          case examplesGitIgnorePath:
-            return '**/a/b/**';
           case sourceGitIgnorePath:
             return '**/*.bad';
           default:
@@ -98,14 +95,13 @@ describe('create-example tool', () => {
         }
       });
       spyOn(glob, 'sync').and.returnValue([
-        'a/', 'a/b/', 'a/c', 'x.ts', 'x.bad', 'a/b/y.ts', 'a/b/y.bad'
+        'a/', 'a/b/', 'a/c', 'x.ts', 'x.bad'
       ]);
       const ensureDirSyncSpy = spyOn(fs, 'ensureDirSync');
       const copySyncSpy = spyOn(fs, 'copySync');
 
       copyExampleFiles('/source/path', '/path/to/test-example', 'test-example');
 
-      expect(readFileSyncSpy).toHaveBeenCalledWith(examplesGitIgnorePath, 'utf8');
       expect(readFileSyncSpy).toHaveBeenCalledWith(sourceGitIgnorePath, 'utf8');
 
       expect(ensureDirSyncSpy.calls.allArgs()).toEqual([

aio/tools/examples/shared/boilerplate/.gitignore

@@ -1,3 +1,4 @@
 **/node_modules/
 **/package-lock.json
 **/yarn.lock
+**/.vscode

aio/tools/transforms/angular-content-package/index.js

@@ -7,8 +7,6 @@
  */
 const Package = require('dgeni').Package;
 const glob = require('glob');
-const ignore = require('ignore');
-const fs = require('fs');
 const path = require('canonical-path');
 const basePackage = require('../angular-base-package');
 const contentPackage = require('../content-package');
@@ -19,25 +17,12 @@ module.exports = new Package('angular-content', [basePackage, contentPackage])
 
   // Where do we get the source files?
   .config(function(readFilesProcessor, collectExamples) {
-
-    const gitignoreFilePath = path.resolve(GUIDE_EXAMPLES_PATH, '.gitignore');
-    const gitignoreFile = fs.readFileSync(gitignoreFilePath, 'utf8');
-    const gitignore = ignore().add(gitignoreFile);
-
     const examplePaths = glob.sync('**/*', { cwd: GUIDE_EXAMPLES_PATH, dot: true, ignore: '**/node_modules/**', mark: true })
-                            .filter(filePath => filePath !== '.gitignore') // we are not interested in the .gitignore file itself
                             .filter(filePath => !/\/$/.test(filePath)); // this filter removes the folders, leaving only files
-    const ignoredExamplePaths = [];
     const resolvedExamplePaths = [];
 
     examplePaths.forEach(filePath => {
-      // filter out files that match the .gitignore rules
-      if (gitignore.ignores(filePath)) {
-        ignoredExamplePaths.push(filePath);
-      } else {
-        // we need the full paths for the filereader
         resolvedExamplePaths.push(path.resolve(GUIDE_EXAMPLES_PATH, filePath));
-      }
     });
 
     readFilesProcessor.sourceFiles = readFilesProcessor.sourceFiles.concat([
@@ -90,7 +75,6 @@ module.exports = new Package('angular-content', [basePackage, contentPackage])
     ]);
 
     collectExamples.exampleFolders.push('examples');
-    collectExamples.registerIgnoredExamples(ignoredExamplePaths, gitignoreFilePath);
   })
 
 

aio/tools/transforms/examples-package/processors/collect-examples.js

@@ -7,24 +7,7 @@ module.exports = function collectExamples(exampleMap, regionParser, log, createD
     $runBefore: ['parsing-tags'],
     $validate: {exampleFolders: {presence: true}},
     exampleFolders: [],
-    ignoredExamples: {},
-    /**
-     * Call this method to indicate to the processor that some files, that actually exist,
-     * have been filtered out from being processed.
-     * @param paths an array of relative paths to the examples that have been ignored.
-     * @param gitIgnorePath the path to the gitignore file that caused this example to be ignored.
-     */
-    registerIgnoredExamples(paths, gitIgnorePath) {
-      paths.forEach(path => { this.ignoredExamples[path] = gitIgnorePath; });
-    },
-    /**
-     * Call this method to find out if an example was ignored.
-     * @param path a relative path to the example file to test for being ignored.
-     * @returns the path to the .gitignore file.
-     */
-    isExampleIgnored(path) {
-      return this.ignoredExamples[path];
-    },
+
     $process(docs) {
       const exampleFolders = this.exampleFolders;
       exampleFolders.forEach(folder => exampleMap[folder] = exampleMap[folder] || {});

aio/tools/transforms/examples-package/processors/collect-examples.spec.js

@@ -188,17 +188,6 @@ describe('collectExampleRegions processor', () => {
       });
     });
   });
-
-  describe('filtered examples', () => {
-    it('should indicate if an example was filtered', () => {
-      processor.registerIgnoredExamples(['c/d/e', 'e/f/g'], 'path/to/gitignore');
-      processor.registerIgnoredExamples(['x/y/z'], 'path/to/other/gitignore');
-      expect(processor.isExampleIgnored('a/b/c')).toBeFalsy();
-      expect(processor.isExampleIgnored('c/d/e')).toEqual('path/to/gitignore');
-      expect(processor.isExampleIgnored('e/f/g')).toEqual('path/to/gitignore');
-      expect(processor.isExampleIgnored('x/y/z')).toEqual('path/to/other/gitignore');
-    });
-  });
 });
 
 

aio/tools/transforms/examples-package/services/getExampleRegion.js

@@ -14,16 +14,9 @@ module.exports = function getExampleRegion(exampleMap, createDocMessage, collect
 
     // If still no file then we error
     if (!exampleFile) {
-      const gitIgnoreFile = collectExamples.isExampleIgnored(relativePath);
-      if (gitIgnoreFile) {
-        const message = createDocMessage('Ignored example file... relativePath: "' + relativePath + '"', doc) + '\n' +
-        'This example file exists but has been ignored by a rule, in "' + gitIgnoreFile + '".';
-        throw new Error(message);
-      } else {
         const message = createDocMessage('Missing example file... relativePath: "' + relativePath + '".', doc) + '\n' +
             'Example files can be found in the following relative paths: ' + EXAMPLES_FOLDERS.map(function(folder) { return '"' + folder + '"'; }).join(', ');
         throw new Error(message);
-      }
     }
 
     var sourceCodeDoc = exampleFile.regions[regionName || ''];

aio/tools/transforms/examples-package/services/getExampleRegion.spec.js

@@ -11,7 +11,6 @@ describe('getExampleRegion', () => {
     collectExamples = injector.get('collectExamples');
     exampleMap = injector.get('exampleMap');
     collectExamples.exampleFolders = ['examples'];
-    collectExamples.registerIgnoredExamples(['filtered/path'], 'some/gitignore');
     exampleMap['examples'] = {
       'test/url': { regions: {
         '': { renderedContent: 'whole file' },
@@ -37,13 +36,6 @@ describe('getExampleRegion', () => {
     }).toThrowError('Missing example region... relativePath: "test/url", region: "missing-region". - doc\nRegions available are: "", "region-1"');
   });
 
-  it('should throw an error if an example has been filtered out', () => {
-    expect(() => {
-      getExampleRegion({}, 'filtered/path', 'any-region');
-    }).toThrowError('Ignored example file... relativePath: "filtered/path" - doc\n' +
-                    'This example file exists but has been ignored by a rule, in "some/gitignore".');
-  });
-
   it('should mark the example as having been "used"', () => {
     const doc1 = {};
     const doc2 = {};