Allow excluding paths from the source directory

[wouterj]

E.g. in the Symfony docs, we must exclude the _build directory from the source directory (the project's root) to not get rst files from dependencies parsed. I can imagine excluding vendor/ makes sense for more repositories.

EDIT: Hah, I didn't know I was submitting this PR right when 1.0.0 was released. Fortunately, the changes in this PR are backwards-compatible so it's completely fine for a 1.1 release.

[linawolf]

@wouterj In the TYPO3 docs we solve this by listening to the PostCollectFilesForParsingEvent and then change the files to be renderered there. Would this be a solution for you? https://github.com/TYPO3-Documentation/render-guides/blob/main/packages/typo3-docs-theme/src/EventListeners/IgnoreLocalizationsFolders.php

[jaapio]

I think this is the better way of doing it, both will work, but this way you are using the power of the file resolver, in phpDocumentor we are using this too to make more complex selections of files. The library used here does even support glob patterns

[wouterj]

Yes, I also considered hooking into the process somewhere but I think it would be quite common (at least excluding vendor/) so it makes sense as a feature.

---

Another solution that I quite like, but requires changing FlyFinder: Allowing to use specifications to "limit" a file system. I'm not sure if it's possible at all in FlySystem, but it would be nice if we can scope all functions in the Filesystem by adding specifications to it.

$origin = (new Filesystem(new Local(__DIR__)))->addPlugin(new Finder());
$origin->scope(new NotSpecification(new InPath('vendor'))); // filter "vendor" from all functions in Filesystem

$commandBus->handle(new ParseDirectoryCommand($origin, '/', 'rst'));

This way, Guides doesn't have to implement this feature itself and users have much more control to specify which files are included and which are not.

Optionally, we can achieve the same by transforming $excludedDirectories into SpecificationInterface[] $extraSpecifications to also allow more complex filter mechanisms being passed by the user (e.g. globing like TYPO3 is doing).

[jaapio]

Not sure I understand what you mean with scope the filesystem. What would that do? Exclude all directories not containing vendor?

[linawolf]

Where do we get $command->getExcludedPaths() from?

[linawolf]

@jaapio, @wouterj how shall we proceed?

[wouterj]

I've changed the implementation a bit, to allow any excluded specification to be passed to the command (not just paths). This gives the maximum extension to users, without introducing any problem.

I also added a console option to exclude paths, as I think this is the most common action.

[jaapio]

Thanks @wouterj this looks good to me 👍

[phpdoc-bot]

💚 All backports created successfully

Status	Branch	Result
✅	1.x

Note: Successful backport PRs will be merged automatically after passing CI.

Questions ?

Please refer to the Backport tool documentation and see the Github Action logs for details