Configurable doctest modules/paths

[NellyWhads]

Reading through docs and usage examples and trying various things myself, I believe there's a usage gap that can be addressed.

As a user of xdoctest in a complex project which include multiple sub-modules, the following questions come to mind:

1. How does a user configure multiple files/modules for xdoctest to run with a single command?
2. How does a user trigger xdoctest with a default configuration for a project?
3. How does a user re-use said configuration with the xdoctest pytest plugin?

Proposal:

1. Add support for running xdoctest on multiple modules at a time.
2. Add support an explicit parameter name for the args option (which after 1., can accept multiple module paths)
3. Expose all of the CLI parameters to the pyproject.toml file under tool.xdoctest
4. Override configured parameters using CLI invocation arguments, of course

This would mimic the behavior of popular tools such as Coverage.py, which allows collecting coverage from specific locations as opposed to only one root module, all configurable through a single tool.coverage section in the pyproject.toml.

[Erotemic]

I generally support this.

There is some pyproject.toml support in src/xdoctest/__main__.py. I'm very open to expanding this.

I think the "-m / --module" argument could be expanded to accept multiple paths to modules to test. That might be the most straightforward way of doing it. I waffle about if the entire "first argument is a command or a path" is good design or not. It is convenient, but it has made implementation messy. Multiple positional arguments can likely also be interpreted as multiple files to test.

I think much of this can be done already if xdoctest is used as a pytest plugin, but on its own it does lack these features. Any implementation should be careful such that a configuration of xdoctest via tool.pytest and tool.xdoctest has intuitive behavior.

[NellyWhads]

Agreed. I actually attempted to get the pytest plugin working but to no avail. I may have too many plugins set up at the moment.

Still, having a single source of default config would make this much more usable by multiple developers without requiring setup with something akin to poethepoet to hide away the complexity of multiple xdoctest calls.

[Erotemic]

@NellyWhads are you interested in working on an implementation? I don't have any cycles for new features at the moment.

[NellyWhads]

Sure, if you don't mind pointing me to the modules where you'd prefer to see this slotted in, I can perhaps take a stab over the winter break

[Erotemic]

There are a few files of interest:

• __main__.py
• doctest_example.py
• runner.py
• plugin.py

The main entrypoint is __main__.py, which is where TOML configuration reading is currently handled.

The doctest_example.py has a class called DoctestConfig, which has doctest-runtime configuration. It has a _populate_from_cli which is what is used to hook it into argparse. There is also a _update_argparse_cli function in runner.py, which has higher level parsing / summary reporting options. Both of these might benefit from some refactoring if you feel inspired, but you may just be able to use them as-is.

The other place to be aware of is in plugin.py, which handles pytest configuration. There is a pytest_addoption method in there which adapts pytest options into native xdoctest options.