Include an example of how to skip all doctests in a module - #2310

I want to skip an entire file, not just doctests in a file.
E.g. put a file kronka_lonka.py with content at the top level

import kronka_lonka

somewhere in the core astropy or an affiliated package and it will be found by the doctest runner and result in an ImportError.

My concrete issue is this: gammapy/gammapy#101

The way we typically deal with that in astropy itself is to not do those kinds of imports at the top level -- i.e. everything is importable by default. Unfortunately, the doctest runner has to import the file to determine if there are any doctests in it.

That said, there is the doctests_norecursedirs option that you can put in the [pytest] section of setup.cfg. It only works with directories, though.

Would it be hard to add a doctests_skipfiles option in addition to doctests_norecursedirs?
Having to create extra directories for the files I want skipped would be messy.

Not sure. Cc: @embray

Ah, right, in #1563 I added a bit so that the code that collects doctests from Python modules will just skip that module if it contains errors. Would that resolve the issue?

I'll try out #1563 and see if it works for my case.
But explicit is better than implicit, so I would prefer a doctests_skipfiles option.

I tried #1563 and it reduces the number of errors I get in gammapy/gammapy#101 .

One remaining issue is e.g. the docs/image/colormap_example.py is still run and hangs with an open matplotlib window I have to close manually.

I want the doctest runner to skip this file, but I don't want it to skip the other files in docs/image.

I think this is good to merge? Even if there are still issues surrounding doctests this PR is only to add a snippet to the docs, so I don't think there's much more to be done.

@embray This doesn't address what I need, but I can file a new issue if you want to merge this now.