Automatically generate output with Sphinx extension

Question

I think I am missing something about the sphinx extension for doctest.

A typical example in the documentation:

.. doctest:: >>> print 1 1 

Is there a way to let sphinx generate output (here: 1 ) automatically?

As I understand it, you can run:

 $ make doctest 

which allows you to check code fragments and compare the actual output with the expected output. For example, if you have

 .. doctest:: >>> print 1 3 

doctest will warn you that you received 1 , expecting 3 .

Instead, I would like sphinx to embed real output only in my docstring or in my .rst file. For example, if we have something like:

 .. doctest:: >>> print 1 >>> print [2*x for x in range(3)] 

I would like it to change docstring to when running make doctest with an option:

 .. doctest:: >>> print 1 1 >>> print [2*x for x in range(3)] [0,2,4] 

I am sure that this is possible and would be very convenient!

Answer 1

I need to (but kindly) advise against what you are trying to do.

What you ask contradicts the "test part" of the doctrine module:

The doctest module looks for pieces of text that look like interactive Python sessions, and then runs those sessions to make sure they work exactly as shown.

There are reasons in these tests if you write the input and the expected result and let Python check if the expected result matches the actual result.

If you give Python the expected result, well ... it will not be expected (from the user / author), so the doctrines will never fail, therefore, these tests will be useless.

Note: If there is no logic inside the function (if / else, while-loops, appends, etc.), there is no need to check them. And the tests should not reproduce the testing logic, otherwise they will no longer test the function.

I found this video about testing-based development very interesting, maybe this may interest you if you want to know more about this argument.

Answer 2

Here is a suggestion on how you could achieve what I suspect you would be looking for:

Doug Hellmann wrote an interesting article entitled Writing Technical Documentation Using Sphinx, Paver, and Cog . It has a section that describes how the Cog tool can be used to automatically run code samples and write output for inclusion in documentation built in Sphinx.

---

There is also an added Sphinx extension called autorun that can execute code in a special runblock and attach the output to the documentation.