ENH: make collection strategy user configurable in the pytest layer

[ev-br]

This is a breaking change: the default collection strategy changes from "api" to vanilla pytest.

Add a cmdline option, --doctest-collect={None, api}

The default is now the vanilla doctest collection, strategy=None. To select strategy='api', use the command flag

$ pytest --doctest-modules --doctest-collect=api

When to use what. strategy='api' is meant for packages with non-trivial internal structure and where you only enfore doctests correctness for public objects.

For individual single-file modules, you probably want strategy=None.

closes gh-114

P.S. I manually checked

• the collection log still agrees with https://github.com/ev-br/scpdt/wiki/Compare-the-coverage
• individual files are no longer skipped: pytest --doctest-modules <path-to-build-install>/scipy/linalg/_basic.py --collect-only gives

<Dir scipy>
  <Dir build-install>
    <Dir lib>
      <Dir python3.10>
        <Dir site-packages>
          <Package scipy>
            <Package linalg>
              <DTModule _basic.py>
                <DoctestItem scipy.linalg._basic.det>
                <DoctestItem scipy.linalg._basic.inv>
                <DoctestItem scipy.linalg._basic.lstsq>
                <DoctestItem scipy.linalg._basic.matmul_toeplitz>
                <DoctestItem scipy.linalg._basic.matrix_balance>
                <DoctestItem scipy.linalg._basic.pinv>
                <DoctestItem scipy.linalg._basic.pinvh>
                <DoctestItem scipy.linalg._basic.solve>
                <DoctestItem scipy.linalg._basic.solve_banded>
                <DoctestItem scipy.linalg._basic.solve_circulant>
                <DoctestItem scipy.linalg._basic.solve_toeplitz>
                <DoctestItem scipy.linalg._basic.solve_triangular>
                <DoctestItem scipy.linalg._basic.solveh_banded>

• We can specify individual functions to doctest: $ python dev.py test --doctests -t scipy/linalg/_basic.py::scipy.linalg._basic.det -v -- --collect-only produces

<Dir scipy>
  <Dir build-install>
    <Dir lib>
      <Dir python3.10>
        <Dir site-packages>
          <Package scipy>
            <Package linalg>
              <DTModule _basic.py>
                <DoctestItem scipy.linalg._basic.det>

Note the need to specify the full dotted name of the doctested object.

[ev-br]

@Sheila-nk WDYT?

[ev-br]

Note to self: remember to update https://github.com/scipy/scipy/pull/20127 when this lands.

[Sheila-nk]

I think it's great you made the collection strategy configurable. Looks good to me! 🚀

[ev-br]

Let's roll with it then. More tweaks are on the way based on the combination of this and gh-133. Thanks Sheila.

[ev-br]

Did not mean to squash-merge. Not a big deal though.