Question

Another way to ask this:
If I wrote doctests in reST, can I use it for Sphinx or other automatic documentation efforts?

Background: I don’t know how to use Sphinx and have not much experience with reST either, so I am wondering if I can use reST-written doctests somewhere else useful than with Sphinx?

Answer 1

Why would I write doctests in restructured text?

You don’t really write the tests “in restructured text”. The interactive examples are the test cases, and it does not matter what the surrounding markup looks like; it could be reST, or it could be something else like Markdown or LaTeX.

reST has been adopted as the “official” markup language for Python documentation, but you are not obligated to use it.

so why is the simple usage example for doctest.testfile() from the doctest documentation then given as a reST file?

Doctest is a way to test code by checking the correctness of embedded interactive examples in documentation, so it makes sense that examples explaining the doctest module also include reST markup.

You can run doctest on text files that contain only interactive input/output examples, and no other content. Those examples could be useful as lightweight unit tests, but on their own they would be less suitable as documentation.

I am wondering if I can use reST-written doctests somewhere else useful than with Sphinx?

Having testable code examples can be useful even if you don’t use Sphinx for your documentation.

If you are looking for alternative documentation tools that understand reST, take a look at docutils (which Sphinx is based on, btw) and its front-end tools, such as rst2html.py.

Another tool that might be of interest is rst2pdf.