Hi @prakhargurunani, thanks a lot for the contribution!

However it is not entirely correct, #7429 is about pytest.skip inside doctests, not at the module level. The examples and docs you provided are using pytest.skip in normal test code.

As an example, see this module (note this is not a test module, but just a normal Python module with doctests on it):

def foobar_pytest_skip():
    """
    >>> import pytest, sys
    >>> if sys.platform.startswith('win'):
    ...     pytest.skip('skip doctest for foobar_pytest_skip on Windows')
    >>> 1 + 2
    3
    >>> "foo" + "bar"
    'foobar'
    """

def foobar_doctest_skip():
    """

    >>> 1 + 4  # doctest: +SKIP
    3
    >>> "foo" + "bar"
    'foobar'
    """

def foobar_pytest_xfail():
    """
    >>> import pytest, sys
    >>> if sys.platform.startswith('win'):
    ...     pytest.xfail('xfail doctest for foobar_pytest_xfail on Windows')
    >>> 1 + 2
    3
    >>> "foo" + "bar"
    'foobar'
    """

Output:

 λ pytest --doctest-modules -v --no-header
======================================= test session starts =======================================
collected 3 items

foo.py::foo.foobar_doctest_skip PASSED                                                       [ 33%]
foo.py::foo.foobar_pytest_skip SKIPPED                                                       [ 66%]
foo.py::foo.foobar_pytest_xfail XFAIL                                                        [100%]

============================= 1 passed, 1 skipped, 1 xfailed in 0.22s =============================

So this example already answers the questions from #7429:

It is not clear where to put this skip-line into. The module? The specific docstring?

It should be in the specific docstring.

Does it apply to every doctest definition in the file?

No, just to that docstring.

It could be mentioned that # doctest: +SKIP skips a single line/doctest, which is what most people search for(?). A sentence if xfailis possible would also be great.

Indeed, the examples above showcase that.

Could you update your PR adding the proper examples and docs? Thanks!

cc @spaceone

Thanks @prakhargurunani!

Took the liberty of taking your examples and improve that section overall. 👍