Generación automática de la salida de doctest con la extensión Sphinx

Question

Creo que me falta algo sobre la extensión de esfinge para doctest.

El ejemplo típico en la documentación es:

.. doctest:: 

    >>> print 1 
    1 

¿No hay una manera de dejar esfinge generar la salida (en este caso: 1) de forma automática?

Por lo que he entendido, es posible ejecutar:

$ make doctest 

que tiene el efecto de probar los fragmentos de código, y comparar la salida real con la salida esperada. Por ejemplo, si usted tiene

.. doctest:: 

    >>> print 1 
    3 

doctest le advertirá que llegó 1 mientras esperaba 3.

En su lugar, me gustaría que sphinx inserte la salida real solo en mi docstring o en mi archivo .rst. Por ejemplo, si tenemos algo como:

.. doctest:: 

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

me gustaría que cuando corremos make doctest con una opción, cambia la cadena de documentación a:

.. doctest:: 

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

estoy seguro de que es posible, y me ser muy conveniente!

Answer 1

Tengo que fuertemente (pero amablemente) desaconseja lo que estás tratando de hacer.

Lo que estamos pidiendo es en contra de la "prueba de parte" de la doctest module:

Las búsquedas módulo doctest para fragmentos de texto que se parecen a las sesiones interactivas de Python, y luego ejecuta esas sesiones para verificar que se trabaja exactamente como se muestra.

Estas pruebas tienen una serie de razones para visitar si usted escribir la entrada y la salida esperada y dejar que Python cheque si la salida esperada coincide con la salida real.

Si deja que Python produzca la salida esperada, bueno ... ya no será esperado (por el usuario/autor), por lo que los doctests nunca fallarán, por lo tanto esas pruebas serán inútiles.

Nota: Si dentro de una función no hay lógica (if/else, while-loops, anexos, etc.) no hay necesidad de probarlos. Y las pruebas no deben reproducir la lógica de prueba, de lo contrario ya no están probando la función.

Encontré this video sobre desarrollo impulsado por prueba muy interesante, tal vez podría ser de su interés si quiere saber más sobre este argumento.

Answer 2

Aquí es una sugerencia sobre cómo se podría lograr lo que sospecha que puede estar buscando:

Doug Hellmann ha escrito un artículo interesante llamado Writing Technical Documentation with Sphinx, Paver, and Cog. Tiene a section que describe cómo se puede usar la herramienta Cog para ejecutar automáticamente ejemplos de código y capturar la salida para incluirla en la documentación construida por Sphinx.

---

También hay un contributed Sphinx extension called autorun que puede ejecutar código en una directiva especial runblock y conecte la salida a la documentación.