Closed skycaptain closed 1 year ago
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.
Julia uses a prompt julia>
: how do they deal with this in their doctests?
Should we try to get it customizable in Sphinx itself?
@cbm755 That might difficult. The problem is that the solution is to monkey-patch docutils
, which is not part of Sphinx directly.
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.
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?
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
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.
I'll try to answer the comments.
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
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.
I've decided not to support this feature.
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:
Instead of:
Not an elegant solution, but one could Monkey-patch this line.