pytest_ignore_collect documentation is misleading

[mgorny]

I'm reporting this as a bug because I've hit this multiple times in the wild in a variety of packages implementing pytest_ignore_collect in conftest.py.

The documentation for pytest_ignore_collect states:

Return True to prevent considering this path for collection.

This hook is consulted for all files and directories prior to calling more specific hooks.

Stops at first non-None result, see firstresult: stop at first non-None result.
(https://pytest.org/en/latest/reference/reference.html#std-hook-pytest_ignore_collect)

While this isn't incorrect, it's misleading. A lot of implementations I've seen assume they're supposed to return False for paths that are not to be ignored. In fact, I didn't realize that returning None was the right thing to do, unless I've found this bit in the changelog:

If after updating to this version you see that your norecursedirs setting is not being respected, it means that a conftest or a plugin you use has a bad pytest_ignore_collect implementation. Most likely, your hook returns False for paths it does not want to ignore, which ends the processing and doesn’t allow other plugins, including pytest itself, to ignore the path. The fix is to return None instead of False for paths your hook doesn’t want to ignore.
(https://pytest.org/en/latest/changelog.html#id141)

Could you please improve the documentation for pytest_ignore_collect to make it clear that normally True or None should be returned? This is especially problematic since returning False makes --ignore silently ignored.

[mgorny]

Thanks! Could you also make it clear that "other plugins" include "built-in" pytest behavior?

[nicoddemus]

I'm short on time, but feel free to open a PR with any other suggestions. 👍