Improve doctest interaction with pytest

[tobiasdiez]

This ticket improves a few things about how doctest treats pytest.

• Introduce the option to specify in function doc TESTS: pytest. This marks the function as tested for the sage-coverage command. Sometimes (but rarely) you have private or protected methods that don't need a proper "EXAMPLES" doctest. In these cases, one can decide to either write traditional TESTS or use pytest to test the method. In the later case, sage-coverage would mark the function as not tested as it's not aware of pytest; so we have to specify explicitly that we use pytest to cover this method. One could even argue that private/protected methods shouldn't be directly tested at all as they are implementation details; but let's not open this discussion.

• Remove _test.py files from doctest coverage. By our convention, these are pytest files and thus almost never have (extensive) doctests.

• To make this work, existing xyz_test.py files that are not using pytest are renamed to test_xyz.py.

CC: @mkoeppe @fchapoton @egourgoulhon @tornaria

Component: doctest coverage

Author: Tobias Diez

Branch/Commit: 01f376c

Reviewer: Matthias Koeppe

Issue created by migration from https://trac.sagemath.org/ticket/32975

[sagetrac-git]

Branch pushed to git repo; I updated commit sha1. New commits:

5851f01

Improve doctest interaction with pytest

[sagetrac-git]

Commit: 5851f01

[mkoeppe]

comment:3

It would probably be a good idea to discuss this in sage-devel at the beginning of the 9.6 development cycle

[mkoeppe]

comment:4

The testsuite failures are unreleated, but the docbuild shows an error:

[sagemath_doc_html-none]   File "/tmp/tmpnq9leusf-sage-git-temp-32975/local/var/lib/sage/venv-python3.9/lib/python3.9/site-packages/sage_docbuild/sphinxbuild.py", line 258, in raise_errors
[sagemath_doc_html-none]     raise OSError(self._error)
[sagemath_doc_html-none] OSError: WARNING: autodoc: failed to import module 'backend_test' from module 'sage.repl.rich_output'; the following exception was raised:
[sagemath_doc_html-none] 

[mkoeppe]

Replying to @tobiasdiez:

• To make this work, existing xyz_test.py files that are not using pytest are renamed to test_xyz.py.

Normally we would have deprecation for such renames, but I think we won't need it here because these modules are only there for testing purposes and will likely not be used in user code

[sagetrac-git]

Branch pushed to git repo; I updated commit sha1. New commits:

e717715	Merge remote-tracking branch 'origin/develop' into public/tests/doctests_pytest
9c5d5a9	Fix docs

[sagetrac-git]

Changed commit from 5851f01 to 9c5d5a9

[tobiasdiez]

comment:8

The docs should be fixed now as well (hopefully).