Skip to content

build(aio): improve ignored example file error message #19265

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Closed
petebacondarwin wants to merge 2 commits into from
Closed

build(aio): improve ignored example file error message #19265

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
87961d6
build(aio): remove commented out code
petebacondarwin Sep 19, 2017
b11f8e2
build(aio): improve error message for ignored example files
petebacondarwin Sep 19, 2017
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
20 changes: 16 additions & 4 deletions aio/tools/transforms/angular-content-package/index.js
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -20,14 +20,25 @@ module.exports = new Package('angular-content', [basePackage, contentPackage])
// Where do we get the source files?
.config(function(readFilesProcessor, collectExamples) {

const gitignoreFile = fs.readFileSync(path.resolve(GUIDE_EXAMPLES_PATH, '.gitignore'), 'utf8');
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 filteredExamplePaths = gitignore.filter(examplePaths) // filter out files that match the .gitignore rules
.map(filePath => path.resolve(GUIDE_EXAMPLES_PATH, filePath)); // we need the full paths for the filereader
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([
{
Expand All @@ -48,7 +59,7 @@ module.exports = new Package('angular-content', [basePackage, contentPackage])
},
{
basePath: CONTENTS_PATH,
include: filteredExamplePaths,
include: resolvedExamplePaths,
fileReader: 'exampleFileReader'
},
{
Expand All @@ -69,6 +80,7 @@ module.exports = new Package('angular-content', [basePackage, contentPackage])
]);

collectExamples.exampleFolders.push('examples');
collectExamples.registerIgnoredExamples(ignoredExamplePaths, gitignoreFilePath);
})


Expand Down
2 changes: 0 additions & 2 deletions aio/tools/transforms/examples-package/index.js
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -5,7 +5,6 @@ module.exports =
new Package('examples', [jsdocPackage])

.factory(require('./inline-tag-defs/example'))
// .factory(require('./inline-tag-defs/exampleTabs'))
.factory(require('./services/parseArgString'))
.factory(require('./services/example-map'))
.factory(require('./file-readers/example-reader'))
Expand All @@ -21,7 +20,6 @@ module.exports =

.config(function(inlineTagProcessor, exampleInlineTagDef) {
inlineTagProcessor.inlineTagDefinitions.push(exampleInlineTagDef);
// inlineTagProcessor.inlineTagDefinitions.push(exampleTabsInlineTagDef);
})

.config(function(computePathsProcessor) {
Expand Down
21 changes: 20 additions & 1 deletion aio/tools/transforms/examples-package/processors/collect-examples.js
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -6,7 +6,26 @@ module.exports = function collectExamples(exampleMap, regionParser, log, createD
$runAfter: ['files-read'],
$runBefore: ['parsing-tags'],
$validate: {exampleFolders: {presence: true}},
$process: function(docs) {
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.
Copy link
Copy Markdown
Member

@gkalpak gkalpak Sep 19, 2017

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Might be worth mentioning that the path is relative to the examples folder.

* @returns the path to the .gitignore file.
*/
isExampleIgnored(path) {
return this.ignoredExamples[path];
},
$process(docs) {
const exampleFolders = this.exampleFolders;
const regionDocs = [];
docs = docs.filter((doc) => {
Expand Down
280 changes: 147 additions & 133 deletions aio/tools/transforms/examples-package/processors/collect-examples.spec.js
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -23,161 +23,175 @@ describe('collectExampleRegions processor', () => {
processor.exampleFolders = ['examples-1', 'examples-2'];
});

it('should identify example files that are in the exampleFolders', () => {
const docs = [
createDoc('A', 'examples-1/x/app.js'), createDoc('B', 'examples-1/y/index.html'),
createDoc('C', 'examples-2/s/app.js'), createDoc('D', 'examples-2/t/style.css'),
createDoc('E', 'other/b/c.js')
];
describe('$process', () => {

processor.$process(docs);
it('should identify example files that are in the exampleFolders', () => {
const docs = [
createDoc('A', 'examples-1/x/app.js'), createDoc('B', 'examples-1/y/index.html'),
createDoc('C', 'examples-2/s/app.js'), createDoc('D', 'examples-2/t/style.css'),
createDoc('E', 'other/b/c.js')
];

expect(exampleMap['examples-1']['x/app.js']).toBeDefined();
expect(exampleMap['examples-1']['y/index.html']).toBeDefined();
expect(exampleMap['examples-2']['s/app.js']).toBeDefined();
expect(exampleMap['examples-2']['t/style.css']).toBeDefined();
processor.$process(docs);

expect(exampleMap['other']).toBeUndefined();
});
expect(exampleMap['examples-1']['x/app.js']).toBeDefined();
expect(exampleMap['examples-1']['y/index.html']).toBeDefined();
expect(exampleMap['examples-2']['s/app.js']).toBeDefined();
expect(exampleMap['examples-2']['t/style.css']).toBeDefined();

it('should remove example files from the docs collection', () => {
const docs = [
createDoc('Example A', 'examples-1/x/app.js'),
createDoc('Example B', 'examples-1/y/index.html'),
createDoc('Other doc 1', 'examples-2/t/style.css', 'content'),
createDoc('Example C', 'examples-2/s/app.js'),
createDoc('Other doc 2', 'other/b/c.js', 'content')
];
expect(exampleMap['other']).toBeUndefined();
});

const processedDocs = processor.$process(docs);
it('should remove example files from the docs collection', () => {
const docs = [
createDoc('Example A', 'examples-1/x/app.js'),
createDoc('Example B', 'examples-1/y/index.html'),
createDoc('Other doc 1', 'examples-2/t/style.css', 'content'),
createDoc('Example C', 'examples-2/s/app.js'),
createDoc('Other doc 2', 'other/b/c.js', 'content')
];

expect(processedDocs.filter(doc => doc.docType === 'example-file')).toEqual([]);
});
const processedDocs = processor.$process(docs);

it('should not remove docs from the docs collection that are not example files', () => {
const docs = [
createDoc('Example A', 'examples-1/x/app.js'),
createDoc('Example B', 'examples-1/y/index.html'),
createDoc('Other doc 1', 'examples-2/t/style.css', 'content'),
createDoc('Example C', 'examples-2/s/app.js'),
createDoc('Other doc 2', 'other/b/c.js', 'content')
];
expect(processedDocs.filter(doc => doc.docType === 'example-file')).toEqual([]);
});

const processedDocs = processor.$process(docs);
it('should not remove docs from the docs collection that are not example files', () => {
const docs = [
createDoc('Example A', 'examples-1/x/app.js'),
createDoc('Example B', 'examples-1/y/index.html'),
createDoc('Other doc 1', 'examples-2/t/style.css', 'content'),
createDoc('Example C', 'examples-2/s/app.js'),
createDoc('Other doc 2', 'other/b/c.js', 'content')
];

const processedDocs = processor.$process(docs);

expect(processedDocs.filter(doc => doc.docType !== 'example-file'))
.toEqual(jasmine.objectContaining([
createDoc('Other doc 1', 'examples-2/t/style.css', 'content'),
createDoc('Other doc 2', 'other/b/c.js', 'content')
]));
});

expect(processedDocs.filter(doc => doc.docType !== 'example-file'))
.toEqual(jasmine.objectContaining([
it('should call `regionParser` from with the content and file extension of each example doc',
() => {
const docs = [
createDoc('Example A', 'examples-1/x/app.js'),
createDoc('Example B', 'examples-1/y/index.html'),
createDoc('Other doc 1', 'examples-2/t/style.css', 'content'),
createDoc('Example C', 'examples-2/s/app.js'),
createDoc('Other doc 2', 'other/b/c.js', 'content')
]));
});
];

it('should call `regionParser` from with the content and file extension of each example doc',
() => {
const docs = [
createDoc('Example A', 'examples-1/x/app.js'),
createDoc('Example B', 'examples-1/y/index.html'),
createDoc('Other doc 1', 'examples-2/t/style.css', 'content'),
createDoc('Example C', 'examples-2/s/app.js'),
createDoc('Other doc 2', 'other/b/c.js', 'content')
];
processor.$process(docs);

processor.$process(docs);
expect(regionParser).toHaveBeenCalledTimes(3);
expect(regionParser).toHaveBeenCalledWith('Example A', 'js');
expect(regionParser).toHaveBeenCalledWith('Example B', 'html');
expect(regionParser).toHaveBeenCalledWith('Example C', 'js');
});

expect(regionParser).toHaveBeenCalledTimes(3);
expect(regionParser).toHaveBeenCalledWith('Example A', 'js');
expect(regionParser).toHaveBeenCalledWith('Example B', 'html');
expect(regionParser).toHaveBeenCalledWith('Example C', 'js');
});

it('should attach parsed content as renderedContent to the example file docs', () => {
const docs = [
createDoc('A', 'examples-1/x/app.js'),
createDoc('B', 'examples-1/y/index.html'),
createDoc('C', 'examples-2/s/app.js'),
createDoc('D', 'examples-2/t/style.css'),
];

it('should attach parsed content as renderedContent to the example file docs', () => {
const docs = [
createDoc('A', 'examples-1/x/app.js'),
createDoc('B', 'examples-1/y/index.html'),
createDoc('C', 'examples-2/s/app.js'),
createDoc('D', 'examples-2/t/style.css'),
];
processor.$process(docs);

processor.$process(docs);
expect(exampleMap['examples-1']['x/app.js'].renderedContent).toEqual('PARSED:A');
expect(exampleMap['examples-1']['y/index.html'].renderedContent).toEqual('PARSED:B');
expect(exampleMap['examples-2']['s/app.js'].renderedContent).toEqual('PARSED:C');
expect(exampleMap['examples-2']['t/style.css'].renderedContent).toEqual('PARSED:D');

expect(exampleMap['examples-1']['x/app.js'].renderedContent).toEqual('PARSED:A');
expect(exampleMap['examples-1']['y/index.html'].renderedContent).toEqual('PARSED:B');
expect(exampleMap['examples-2']['s/app.js'].renderedContent).toEqual('PARSED:C');
expect(exampleMap['examples-2']['t/style.css'].renderedContent).toEqual('PARSED:D');
});

});
it('should create region docs for each region in the example file docs', () => {
const docs = [
createDoc('/* #docregion X */\nA', 'examples-1/x/app.js'),
createDoc('<!-- #docregion Y -->\nB', 'examples-1/y/index.html'),
createDoc('/* #docregion Z */\nC', 'examples-2/t/style.css'),
];

const newDocs = processor.$process(docs);

expect(newDocs.length).toEqual(3);
expect(newDocs).toEqual([
jasmine.objectContaining({
docType: 'example-region',
name: 'dummy',
id: 'examples-1/x/app.js#dummy',
contents: 'js'
}),
jasmine.objectContaining({
docType: 'example-region',
name: 'dummy',
id: 'examples-1/y/index.html#dummy',
contents: 'html'
}),
jasmine.objectContaining({
docType: 'example-region',
name: 'dummy',
id: 'examples-2/t/style.css#dummy',
contents: 'css'
})
]);
});

it('should create region docs for each region in the example file docs', () => {
const docs = [
createDoc('/* #docregion X */\nA', 'examples-1/x/app.js'),
createDoc('<!-- #docregion Y -->\nB', 'examples-1/y/index.html'),
createDoc('/* #docregion Z */\nC', 'examples-2/t/style.css'),
];

const newDocs = processor.$process(docs);

expect(newDocs.length).toEqual(3);
expect(newDocs).toEqual([
jasmine.objectContaining({
docType: 'example-region',
name: 'dummy',
id: 'examples-1/x/app.js#dummy',
contents: 'js'
}),
jasmine.objectContaining({
docType: 'example-region',
name: 'dummy',
id: 'examples-1/y/index.html#dummy',
contents: 'html'
}),
jasmine.objectContaining({
docType: 'example-region',
name: 'dummy',
id: 'examples-2/t/style.css#dummy',
contents: 'css'
})
]);
it('should attach region docs to the example file docs', () => {
const docs = [
createDoc('/* #docregion X */\nA', 'examples-1/x/app.js'),
createDoc('<!-- #docregion Y -->\nB', 'examples-1/y/index.html'),
createDoc('/* #docregion Z */\nC', 'examples-2/t/style.css'),
];

processor.$process(docs);

expect(exampleMap['examples-1']['x/app.js'].regions).toEqual({
dummy: {
docType: 'example-region',
path: 'examples-1/x/app.js',
name: 'dummy',
id: 'examples-1/x/app.js#dummy',
aliases: ['examples-1/x/app.js#dummy'],
contents: 'js'
}
});
expect(exampleMap['examples-1']['y/index.html'].regions).toEqual({
dummy: {
docType: 'example-region',
path: 'examples-1/y/index.html',
name: 'dummy',
id: 'examples-1/y/index.html#dummy',
aliases: ['examples-1/y/index.html#dummy'],
contents: 'html'
}
});
expect(exampleMap['examples-2']['t/style.css'].regions).toEqual({
dummy: {
docType: 'example-region',
path: 'examples-2/t/style.css',
name: 'dummy',
id: 'examples-2/t/style.css#dummy',
aliases: ['examples-2/t/style.css#dummy'],
contents: 'css'
}
});
});
});

it('should attach region docs to the example file docs', () => {
const docs = [
createDoc('/* #docregion X */\nA', 'examples-1/x/app.js'),
createDoc('<!-- #docregion Y -->\nB', 'examples-1/y/index.html'),
createDoc('/* #docregion Z */\nC', 'examples-2/t/style.css'),
];

processor.$process(docs);

expect(exampleMap['examples-1']['x/app.js'].regions).toEqual({
dummy: {
docType: 'example-region',
path: 'examples-1/x/app.js',
name: 'dummy',
id: 'examples-1/x/app.js#dummy',
aliases: ['examples-1/x/app.js#dummy'],
contents: 'js'
}
});
expect(exampleMap['examples-1']['y/index.html'].regions).toEqual({
dummy: {
docType: 'example-region',
path: 'examples-1/y/index.html',
name: 'dummy',
id: 'examples-1/y/index.html#dummy',
aliases: ['examples-1/y/index.html#dummy'],
contents: 'html'
}
});
expect(exampleMap['examples-2']['t/style.css'].regions).toEqual({
dummy: {
docType: 'example-region',
path: 'examples-2/t/style.css',
name: 'dummy',
id: 'examples-2/t/style.css#dummy',
aliases: ['examples-2/t/style.css#dummy'],
contents: 'css'
}
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');
});
});
});
Expand Down
Loading