11
votes

Générer automatiquement la sortie doctest avec une extension Sphinx

Je pense que je manque quelque chose à propos de l'extension Sphinx pour DOCTest.

L'exemple typique de la documentation est le suivant: p> xxx pré>

n'est pas un moyen de laisser Sphinx génère la sortie (ici: 1 code>) automatiquement? p>

Aussi loin que j'ai compris, il est possible de courir: p> xxx pré>

qui a pour effet de tester les extraits de code et de comparer la sortie réelle avec la sortie attendue. Par exemple, si vous avez p>

.. doctest::

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


0 commentaires

3 Réponses :


9
votes

Je dois fortement (mais gentiment) conseiller contre ce que vous essayez de faire.

Ce que vous demandez est contre la "partie de test" du Module Doctest :

Le module Doctest recherche des morceaux de texte qui ressemblent à des sessions de Python interactifs, puis exécutes ces sessions pour vérifier qu'ils fonctionnent exactement comme indiqué.

Ces tests ont des raisons d'être si vous écrivez l'entrée et de la sortie attendue et laissez Python vérifier si la sortie attendue correspond à la sortie réelle.

Si vous laissez Python produira la sortie attendue, bien .. il ne sera plus attendu (par l'utilisateur / auteur), de sorte que les Doctests ne manqueront jamais, d'où ces tests seront inutiles.

Remarque: Si dans une fonction, il n'y a pas de logique (si / sinon, alors que des boucles, ajoute, etc.) Il n'y a pas besoin de les tester. Et les tests ne doivent pas reproduire la logique de test, sinon ils ne testent plus la fonction.

J'ai trouvé Cette vidéo sur le développement axé sur les tests très intéressants, Peut-être que cela pourrait vous intéresser si vous voulez en savoir plus sur cet argument.


2 commentaires

Merci ! Je me rends compte que j'ai mal compris le but de cette extension Sphinx. Je pense que c'était plus un moyen d'écrire le doc de manière plus rapide, mais je comprends maintenant toute l'idée derrière la doctest.


La demande de l'OP était très raisonnable et constitue une caractéristique commune dans la plupart des cadres de test d'entrée-sortie (généralement appelé «accepter» la sortie d'un test). Notez que l'OP a demandé un moyen de mettre à jour les fichiers source (docstrings dans les programmes Python et les blocs de doctest dans Sphinx), pas les sorties générées par Sphinx (HTML ou Latex). Cela serait très utile d'avoir comme moyen de mettre à jour automatiquement les tests et les exemples obsolètes.



7
votes

Voici une suggestion sur la façon dont vous pourriez réaliser ce que je soupçonne que vous pourriez rechercher:

Doug Hellmann a écrit un article intéressant appelé Écrire une documentation technique avec Sphinx, Paver et Cog . Il a une section décrivant comment le L'outil Cog peut être utilisé pour automatiquement Exécutez des exemples de code et capturez la sortie pour l'inclusion dans la documentation construite SPHINX.

Il y a aussi un Extension Sphinx apportée appelée Autorun qui peut exécuter du code dans une spéciale Runblock directive et joignez la sortie à la documentation.


0 commentaires

0
votes

Cette fonctionnalité est disponible dans le cadre de pytest-accepter et l'extension de Pytest : https://github.com/max-sixty/pytest-Accept

Quote:

Pytest-Accept est un plugin pytest pour la mise à jour automatique du Doctest les sorties. Il exécute des doctestes, observe les sorties générées et écrit aux sorties documentées des doctestes.

Il est conçu pour quelques cas d'utilisation:

  • Les personnes qui travaillent avec des doctestes et ne jouissent pas de la copie manuelle des sorties générées du journal des erreurs Pytest et de les coller dans leurs sorties documentées des doctestes. Pytest-accepter fait la copie et coller pour vous.
  • Les gens qui trouvent généralement des tests d'écriture un peu ennuyeux et préfèrent se développer en "exécutant le code et voir si cela fonctionne". Cette La bibliothèque vise à faire tester une partie joyeuse de cette boucle de développement.

0 commentaires