Directives should only be specified inline

[catch22]

I was thinking that perhaps we should not allow to pass directives as part of the doctest call. Instead, all directives should be specified inline (as comments in the actual doctests). My rationale is that doctests should be self-documenting and self-contained: it should always be possible to call doctest <function>.

Let me know what you think; I'm happy to provide a PR.

[cbm755]

A much weaker position would be allow it but stop advertising it at the top of doctest.m's help text: I'd be ok with that for 0.4.x.

[catch22]

Sounds good! Do you have any thoughts on eventually phasing out that capability?

[cbm755]

Have not really thought about it yet. As a general rule, fewer knobs is good: add them once support them forever.

But to add a data point: I think Python doctest does allow specifying directives globally. No idea how much this is used in practice.

[cbm755]

While we're thinking about this project again, should we at least take the "weaker position" mentioned above?

[catch22]

Just out of curiosity - have you ever found a use case for this functionality?

[cbm755]

No, not in practice.

I guess theoretically the WHITESPACE one could be used in this way: I figured projects might have project-wide preferences about these things...

[catch22]

That's true. I feel that it is desirable that doctest <target> always works -- possibly after some setup script has been run that configures paths etc. One might also want to run doctests for targets in different projects, so this seems to preclude any solution that modifies the default directives by setting some global variables.

I think doctest could load the closest .doctestrc file in the target's directory or one of its parent directories before running doctests. I can't think of a major downside (it should be reasonably fast since it will only be done once for invocations like doctest .), but am not so inclined to implement it without a user/use case.

How about we (1) deprecate and subsequently remove support for specifying directives at the command level in the next major version, and (2) accept patches for adding project-global support for modifying directives (using e.g. a .doctestrc file).