Deprecate collecting 'test*.txt' files as doctests, replaced by 'test_*.txt'

[nicoddemus]

I've always thought odd that the pattern for collecting doctest files is test*.txt, while for Python files is test_*.py and *_test.py.

How about we deprecate collecting test*.txt files? Sometimes this tries to collect files which are not test files and can be a source of confusion (#5445 is the most recent example of this but I'm sure there are more). We could emit a warning when we collect such a file and the user did not specify that option explicitly.

After that we should decide to which pattern we should collect by default then:

1. test_*.txt.
2. test_*.rst.
3. Do not collect doctests by default.

[RonnyPfannschmidt]

the intent here is simple, doctests in documentation have no test prefix

we should reqire however to tell pytest the documentation folders/files more explicit (aka doctest_collectroot as a ini option)

[nicoddemus]

the intent here is simple, doctests in documentation have no test prefix

Not sure what you mean, as only test*.txt files are collected as tests?

[RonnyPfannschmidt]

indeed, i missremembered,

pytest/src/_pytest/doctest.py

Lines 100 to 107 in 240828d

	def _is_doctest(config, path, parent):
	if path.ext in (".txt", ".rst") and parent.session.isinitpath(path):
	return True
	globs = config.getoption("doctestglob") or ["test*.txt"]
	for glob in globs:
	if path.check(fnmatch=glob):
	return True
	return False

is scarry

[nicoddemus]

I'm leaning towards that 3) might be the best option:

• Doctests are not widely used, so makes sense to make them opt-in.
• Principle of least surprise: it is kind of surprising that test*.txt are collected as test files. While it might be innocuous (nothing happens if there are no doctests inside the files), it might be lead to confusing errors.