自動生成帶有Sphinx擴展名的doctest輸出

Question

我想我缺少一些關於doctest的sphinx擴展。

文檔中最典型的例子是：

.. doctest:: 

    >>> print 1 
    1 

是不是有什麼辦法可以讓獅身人面像生成輸出（此處：1）自動？

據我的理解，它可以運行：

$ make doctest 

其中有測試代碼片段，並比較預期輸出的實際輸出效果。舉例來說，如果你有

.. doctest:: 

    >>> print 1 
    3 

文檔測試會提醒你，它得到了1同時期待3。

相反，我希望sphinx將真實的輸出單獨插入到我的文檔字符串或我的.rst文件中。例如，如果我們有這樣的：

.. doctest:: 

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

我想，當我們用一個選項運行make doctest，它改變了文檔字符串：

.. doctest:: 

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

我敢肯定，這是可能的，而且會非常方便！

Answer 1

我必須強烈地（但友好地）建議您對你正在嘗試做什麼。

什麼你問的是對doctest module的「測試部分」：

文本的碎片，看起來像交互式Python會話，然後執行這些會話，以驗證文檔測試模塊查找它們完全按照所示工作。

這些測試有一個原因是，如果你寫輸入和預期的輸出，讓Python的檢查，如果預期輸出與實際輸出。

如果你讓Python產生預期的輸出，那麼它將不再是預期（由用戶/作者），所以doctests永遠不會失敗，因此這些測試將是無用的。

說明：如果函數內部沒有邏輯（if/else，while循環，附加等等），則不需要測試它們。測試不能重現測試邏輯，否則他們不再測試該功能。

我發現this video關於測試驅動開發非常有趣，也許如果你想知道更多關於這個論點的信息，你可能會感興趣。

Answer 2

這裏是你如何能做到什麼，我懷疑你可能會尋找一個建議：

道格·海爾曼寫了一篇有趣的文章名爲Writing Technical Documentation with Sphinx, Paver, and Cog。它有a section描述如何使用Cog工具自動運行代碼示例並捕獲輸出以包含在Sphinx構建的文檔中。

---

還有一個contributed Sphinx extension called autorun，可以在一個特殊的 runblock指令執行代碼，並附加輸出的文檔。