0

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?

K.-Michael Aye
  • 5,465
  • 6
  • 44
  • 56
  • nothing, i don't know how to use Sphinx, just have read about it and have not much experience with reST either. Frankly, I am a bit *scared* of Sphinx and its required overhead, so I am just wondering if there is any benefit in writing doctests in reST if I do NOT use Sphinx? Is there anything simpler that can make use of the fact that I wrote my doctests in reST? – K.-Michael Aye May 18 '12 at 22:20
  • I don't understand your question: do you mean to include doctests in a separate documentation written in rst? or add rst to your docstrings? you don't really need rst for doctests, but for documentation. – bmu May 18 '12 at 23:11
  • so why is the simple usage example for doctest.testfile() from the doctest documentation then given as a reST file? http://docs.python.org/dev/library/doctest.html , section 25.2.2 – K.-Michael Aye May 18 '12 at 23:28
  • @K.-MichaelAye It is often used together and it makes sense that you can test the examples you give in your documentation with doctest. see also mzjn's answer. – bmu May 19 '12 at 12:31

2 Answers2

2

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.

mzjn
  • 48,958
  • 13
  • 128
  • 248
0

Adding doctests to your documentation makes sense to ensure that code in your documentation is actually working as expected. So, you're testing your documentation. For general code-testing, using doctests can't be recommended at all.

funky-future
  • 3,716
  • 1
  • 30
  • 43