Hey all,
After getting tired of Sphinx not regenerating plots incrementally, I created a script that reads the docstring of a given function, and either runs the code in the docstring, or writes it to a file. The code is at
The program expects two command line arguments. The first must be one of write, irun or run. The second argument is the fully qualified name of a SciPy function (or any SciPy object with a docstring).
For example,
python extract_example_code.py write scipy.stats.median_test
will write the Python code found in the Examples section of the docstring of scipy.stats.median_test to the file example_median_test.py.
The irun command (short for interactive run) runs the code in the Examples section. It will show each line of code as it is executed. There is some logic built-in that attempts to identify when the result should also be echoed to the terminal. (This behavior is not perfect, but it has been good enough for my uses so far.)
For example,
% python extract_example_code.py irun scipy.stats.median_test
>>> g1 = [10, 14, 14, 18, 20, 22, 24, 25, 31, 31, 32, 39, 43, 43, 48, 49]
>>> g2 = [28, 30, 31, 33, 34, 35, 36, 40, 44, 55, 57, 61, 91, 92, 99]
>>> g3 = [0, 3, 9, 22, 23, 25, 25, 33, 34, 34, 40, 45, 46, 48, 62, 67, 84]
>>> from scipy.stats import median_test
>>> res = median_test(g1, g2, g3)
>>> res.median
np.float64(34.0)
>>> res.table
array([[ 5, 10, 7],
[11, 5, 10]])
>>> res.pvalue
np.float64(0.12609082774093242)
>>> res = median_test(g1, g2, g3, lambda_="log-likelihood")
>>> res.pvalue
np.float64(0.12224779737117829)
>>> res = median_test(g1, g2, g3, ties="above")
>>> res.pvalue
np.float64(0.06387327606955327)
>>> res.table
array([[ 5, 11, 9],
[11, 4, 8]])
The outputs shown above are the result of executing the code. They are not simply copied from the docstring.
Note that irun injects the setting of matplotlib parameters that were copied from our conf.py, so any plots that are generated should look the same as those generated when the docs are built with Sphinx.
The run command simply runs the code and returns. If the code does not generate plots or output with print() calls, and does not generate any warnings or errors, the run command will return with no output.
I’ve been using this when working on a docstring that contains one or more plots. In my experience, rerunning Sphinx does not reliably regenerate the updated plot, so instead of rerunning Sphinx, I use this script to see the plot generated by the updated docstring.