Build enhancement: Test in-docstring example code as part of CI

[pushfoo]

TL;DR:

Sometimes our example code is wrong and we can run it as part of CI to fix that.

Doctest

Our actual tests would stay where they are. The purpose of doctest would be to run example code in docstrings to make sure they execute. It has configurable pytest integration and can run against .rst files.

Example use case

In #973, there was a commit which had example code referencing a non-existent member of the pyglet module. Although it's an internal debug function, it would still make sense to check it. This even more important for user-facing example code and some of the doc.

I believe I configured this for arcade or another project at one point, so it should be a matter of copying config more than getting the technology working.

[benmoran56]

This is worthwhile to pursue.
Many of the docstrings are missing code like import pyglet for brevity, so there will likely be lots of small updates to get things in line. We also want to take care not to add too much code to the docstrings. They are best for bare minimum, or "quick start" examples, and leave the detailed code to the programming guide.

[pushfoo]

To keep docstring example code brief, I think the following steps make sense:

1. Declare shared setup (import pyglet, etc) using the only directive to keep in-docstring example code brief.
2. Cross-reference full runnable examples

The only directive can be used to do this:

.. only:: doctest
   This will only be run / included during doctest runs

Although some of the pytest integrations look a little ugly as source, doc readers won't see any of them.

[benmoran56]

Sounds good to me.