如何記錄Python代碼：Epydoc，doxygen，Sphinx，...？

Question

我不確定我是否應該使用Epydoc或doxygen來記錄我的Python代碼。目前我更喜歡Epydoc，因爲它專門用於Python，它的語法與doxygen（我用於記錄我的C/C++代碼到目前爲止）沒有太大差別。

針對Epydoc或使用doxygen的任何參數？

• http://epydoc.sourceforge.net/
• http://www.doxygen.org/
• http://sphinx.pocoo.org/

Answer 1

epydoc的已經用於文檔生成的經典工具。然而，最近每個人都轉向獅身人面像。

你應該使用epydoc或者你可以嘗試使用sphinx。 Python的文檔本身是使用sphinx完成的。獅身人面像可以爲您提供更多的控制和更好的文檔。

• http://sphinx-doc.org/

沒有什麼錯doxygen的，但它提供了對C/C++程序受益匪淺。由於Python代碼有專門的文檔工具，因此它們可以更好地控制文檔生成。

Answer 2

我試過獅身人面像，epydoc和doxygen爲我的python項目。

獅身人面像沒有爲我工作，因爲它取決於能夠導入每個模塊。儘管我的項目運行良好，Sphinx可以找到它的模塊，但Sphinx無法導入大多數模塊。獅身人面像可能對一般文檔和創建用戶手冊很有用，但至少對於記錄我的源代碼是沒有用的。看來Sphinx模塊必須能夠獨立運行。但在我的項目中，第一個模塊嘗試連接到數據庫。如果數據庫連接失敗，則停止。許多其他模塊期望數據庫遊標。如果數據庫連接未建立，則無法導入，因此Sphinx失敗。

Doxygen做得很好。如果與doxypy結合，它會更好。但是它有一些缺點。如果您想在源代碼中使用編號列表，您不會在文檔中獲取它，反之亦然。 此外，如果閱讀文檔，源代碼不可見。

所以我試了Epydoc。儘管Epydoc未超過3年更新並因此而死亡，但對我來說，它證明是迄今爲止記錄python代碼的最佳工具。 與Sphinx一樣，Epydoc嘗試導入每個模塊，但是如果導入失敗，它只會顯示一條錯誤消息，然後嘗試解析模塊，就像doxygen那樣。 由Epydoc生成的文檔非常好，與doxygen相比具有一些優勢： 1.記錄的源文件只需單擊即可顯示。 2.文檔中的編號列表也在文檔中編號。

如果easy_install無法連接到互聯網，安裝Sphinx相當複雜。這是因爲獅身人面像依賴於其他軟件包。 Doxygen可以像安裝程序一鍵安裝的大多數程序一樣簡單安裝。但DoxyPy和可能是gaphviz也應該安裝。 只需單擊一次即可安裝Expydoc，但在Windows 7上，這需要以管理員身份明確完成，而Epydoc安裝程序不會檢查自身是否以足夠的權限啓動。 012xx獲得我的項目的第一個可用文檔是Epydoc迄今爲止最簡單和最快的。 最後Epydoc仍然可以被推薦爲最好的工具來記錄python項目。獅身人面像可能是製作用戶文檔的好工具。