Repository navigation
Configurable doctest modules/paths #167
Description
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:
- How does a user configure multiple files/modules for
xdoctestto run with a single command? - How does a user trigger
xdoctestwith a default configuration for a project? - How does a user re-use said configuration with the
xdoctestpytest plugin?
Proposal:
- Add support for running
xdocteston multiple modules at a time. - Add support an explicit parameter name for the
argsoption (which after 1., can accept multiple module paths) - Expose all of the CLI parameters to the
pyproject.tomlfile undertool.xdoctest - 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.
Activity
Erotemic commentedon Dec 29, 2024
I generally support this.
There is some
pyproject.tomlsupport insrc/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.pytestandtool.xdoctesthas intuitive behavior.NellyWhads commentedon Dec 29, 2024
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
poethepoetto hide away the complexity of multiplexdoctestcalls.Erotemic commentedon Dec 29, 2024
@NellyWhads are you interested in working on an implementation? I don't have any cycles for new features at the moment.
NellyWhads commentedon Dec 30, 2024
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 commentedon Dec 31, 2024
There are a few files of interest:
__main__.pydoctest_example.pyrunner.pyplugin.pyThe main entrypoint is
__main__.py, which is where TOML configuration reading is currently handled.The
doctest_example.pyhas a class calledDoctestConfig, which has doctest-runtime configuration. It has a_populate_from_cliwhich is what is used to hook it into argparse. There is also a_update_argparse_clifunction inrunner.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 apytest_addoptionmethod in there which adapts pytest options into native xdoctest options.