Add support for Matlab style doctests

[skycaptain]

We're using Sphinx for generating HTML docs out of help texts. We would like to use catch22/octave-doctest for running tests on the examples in docstrings. Sphinx recognizes doctests starting with >>> and formats them as accordingly. octave-doctest however requires doctests starting with >>. See discussion here https://github.com/catch22/octave-doctest/pull/236.

This would allow us to use:

function number = getMyNumber()
% Returns the number
%
%   Returns:
%       number (numeric): The number
%
%   Example:
%       >> getMyNumber()
%       5
%
    number = 5;
end

Instead of:

function number = getMyNumber()
% Returns the number
%
%   Returns:
%       number (numeric): The number
%
%   Example:
%       ::
%
%           >> getMyNumber()
%           5
%
    number = 5;
end

Not an elegant solution, but one could Monkey-patch this line.

[joeced]

Thanks for the suggestion. I think it's a nice idea and I tried out your monkey-patching idea, which works as expected (and is easy to implement).

I think I will add a new option, matlab_enable_doctest, which will do the monkey-patching. Does that sound OK?

Edit:

I implemented the feature (and it works), but I have to find a way to test it reliably.

[cbm755]

Julia uses a prompt julia>: how do they deal with this in their doctests?

Should we try to get it customizable in Sphinx itself?

[joeced]

@cbm755 That might difficult. The problem is that the solution is to monkey-patch docutils, which is not part of Sphinx directly.

[cbm755]

Thanks, I see.

This is mentioned under http://docutils.sourceforge.net/docs/dev/todo.html "Generalize the doctest block construct (which is overly Python-centric) to other...". But at least one person "spoke out against this idea".

So I guess a local fix here is certainly quicker.

[skycaptain]

Nice one! Just one more thing, that came to my mind: How does this affect mixed environments, where we have Python and Matlab code? The patch is global I guess and not per-file?

[skycaptain]

Another thing that came to my mind: Does Sphinx break the highlighting after one empty line. See the discussion we had over at https://github.com/catch22/octave-doctest/issues/239

[cbm755]

The to-be-written manual for octave-pythonic might want to mix Python and Octave doctests in the same document. CC @mtmiller.

I'm not a Sphinx/Docutils user yet so maybe this is not useful... Can we write some kind of thing like https://www.sympy.org/sphinx-math-dollar/ but that munges >>-style doctests into whatever format Docutils wants? (i.e., with <BLANKLINE> and whatever conventions).

I'd be happy to collaborate on the parsing of octave-doctest Doctests if that were helpful---i.e., we could factor that out a bit.

[joeced]

I'll try to answer the comments.

• Unfortunately autodoc with matlab and python does not play well as reported in #63.
• Sphinx breaks the highlighting after one blank line.
• The idea from @cbm755 might work better, although it requires one to make yet another module.

I pushed the first hacked version to https://github.com/sphinx-contrib/matlabdomain/tree/doctests so you can try it out.

You can install it locally (preferably in a virtual environment) with

pip install git+https://github.com/sphinx-contrib/matlabdomain.git/@doctests

[joeced]

I just released a new version, 0.10.0, where Python and MATLAB code can be documented together (closed #63), which probably makes it a lot more difficult to use the proposed hack.

Another solution could be to connect to the autodoc-process-docstring as Napoleon extension does and scan for >> or whatever doctests symbol should be used.

[joeced]

I've decided not to support this feature.