Doctests

[Fredrik Averpil]

Hi,

Is anyone using doctest in sphinx/rst?

Does this work well, or would you say it is more preferable to keep doctests separate?

Cheers,

Fredrik

[Marcus Ottosson]

Doctests are typically written within the docstring of a function or class. How do you mean using them with sphinx? And how do you mean keeping them separate? Separate from what?

--
You received this message because you are subscribed to the Google Groups "Python Programming for Autodesk Maya" group.
To unsubscribe from this group and stop receiving emails from it, send an email to python_inside_m...@googlegroups.com.
To view this discussion on the web visit https://groups.google.com/d/msgid/python_inside_maya/CAD%3DwhWPjXqVe5KOg78OLCH2jbDwtvk%3Dz4bQKUJOA41Xm3V4fQg%40mail.gmail.com.
For more options, visit https://groups.google.com/d/optout.

--

Marcus Ottosson
konstr...@gmail.com

[Fredrik Averpil]

Doctests are typically written within the docstring of a function or class. How do you mean using them with sphinx? And how do you mean keeping them separate? Separate from what?

You can define doctests (in docstrings) and then test them via Sphinx by running make doctest:
http://sphinx-tutorial.readthedocs.io/step-3/#test-your-docs

In my mind, code for some tests could become quite large, and would make the docstring big. Tests would also become scattered around your application. So I’m thinking I’d probably rather run tests completely separated from Sphinx.

I’m sure doctests via Sphinx has its use cases, and I was interested in what you guys thought of this and if any of you were using it this way.

// Fredrik

​

[Fredrik Averpil]

So I’m thinking I’d probably rather run tests completely separated from Sphinx.

Sorry, I meant to say I’d rather run tests not defined in docstrings… and instead define them in separate file(s), outside of my application and outside of docstrings/Sphinx.

​

[Marcus Ottosson]

Ah, I see.

Well, in my experience, unittests and doctests serve two different purposes. The former is for ensuring the correctness of the program whereas the latter is for communicating use, very much like an example. Because, as you say, doctests can get quite large, each doctest forces you to think about the minimal interface to any function, and forces you to realise what it is dependent on by what you have to do so set the function up in the example code. Less is often better.

I typically run doctest alongside running tests, via nose that would be something along the lines of passing --with-doctest to the command-line interface. In addition, I tend to stick with the overall mental model of having tests either as a doctest, or as a unittest, such that they both don’t end up testing the same thing. Though it’s mostly about balance and what’s the most maintainable and makes the most sense.

I would run them via sphinx, but only as a measure of ensuring that what I’ve written is runnable, so that the documentation is correct. I would not rely on sphinx (or any documentation) to determine the correctness of the program, that’s backwards.

Example

def my_function(arg1=True):
  """A great function

  Arguments:
    arg1 (bool, optional): Whether or not to be great

  Example:
    >>> value = True
    >>> my_function(value)
    False

  Returns:
    bool: Inverse of input argument

  """

  # implementation here

This for example communicates both what a function takes as input, and what it produces as output. The same information can be found under Arguments and Returns, but the example can be physically tested for correctness, whereas the others are used by programs like sphinx to do HTML formatting. In an ideal world, they would have a form of correlation such that they couldn’t provide differing information, but such is life.

​

On 30 June 2016 at 06:07, Fredrik Averpil <fredrik...@gmail.com> wrote:

So I’m thinking I’d probably rather run tests completely separated from Sphinx.

Sorry, I meant to say I’d rather run tests not defined in docstrings… and instead define them in separate file(s), outside of my application and outside of docstrings/Sphinx.

​

--

You received this message because you are subscribed to the Google Groups "Python Programming for Autodesk Maya" group.
To unsubscribe from this group and stop receiving emails from it, send an email to python_inside_m...@googlegroups.com.

To view this discussion on the web visit https://groups.google.com/d/msgid/python_inside_maya/CAD%3DwhWO1wGQn%3D8XhS8HypavmDP%3DeNzoxdjE%3DauD4rGWOW9vcVw%40mail.gmail.com.

For more options, visit https://groups.google.com/d/optout.

--

Marcus Ottosson
konstr...@gmail.com

[Fredrik Averpil]

What you say makes a whole lot of sense. Thank you for the detailed answer! :)

I’m right now setting up both tests and sphinx for a large project I’m making compatible with Python2/3, PySide/PySide2/PyQt5 (via Qt.py). So a whole lot of stuff can go wrong and needs to get tested. I totally see what you say makes sense in my scenario!

Cheers,
Fredrik

​

[Justin Israel]

For what its worth, the Go language also makes use of the equivalent of sphinx doctests's, for the same purpose that Marcus described. They are used to write examples of usage, which also automatically become unittests that have to pass. It enforces working examples, so that they don't go out of date when code changes, when someone forgets to update the text:

Explanation:

https://blog.golang.org/examples

Live Examples from stdlib docs:

https://golang.org/pkg/strings/#Contains

Justin

--

You received this message because you are subscribed to the Google Groups "Python Programming for Autodesk Maya" group.
To unsubscribe from this group and stop receiving emails from it, send an email to python_inside_m...@googlegroups.com.

To view this discussion on the web visit https://groups.google.com/d/msgid/python_inside_maya/CAD%3DwhWP%3DakWH1VS3fmVWaWLt6UOWakTwAeYLapipG-Qfm%3DF35Q%40mail.gmail.com.