使用epydoc記錄公共全局函數

Question

我有一個包含多個全局函數和一個全局變量的模塊。這個變量和一些函數遵循Python的'私人'命名約定，並且帶有前導下劃線。其他功能旨在公開，並且沒有領先的下劃線。

我已經在我的文件開頭聲明瞭__all__，列出了我的公共函數名稱。

當試圖使用epydoc生成此模塊的文檔時，epydoc正在考慮模塊中的所有內容都是私有的。而且，由於我使用的是--no-private標誌，這意味着輸出僅顯示模塊本身的文檔，而不顯示模塊的元素或其各自的文檔。

如果我不使用epydoc的--no-private標誌，所有的事情都會被記錄下來。但我不想要私人的東西在那裏。這裏是踢球者：如果我註釋掉我的__all__，epydoc只能正確記錄我的模塊的公共元素。

我是一個相對的Python新手，但據我所知，__all__是爲了讓你擺脫麻煩，當你導入其他模塊，然後其他模塊導入你的，並試圖保持更緊的東西當一切都是技術上公衆，只要你知道你想要訪問的名稱。忽略__all__可能導致Bad Things™，或者我被告知。與此同時，epydoc聲稱，它決定公開什麼是公開的，什麼不公開。

是我使用epydoc錯誤，假設我的代碼中使用__all__錯誤或者epydoc中有錯誤？ （我已經解決了epydoc中的一個錯誤處理錯誤，這顯然是由較新版本的docutils造成的。）

Answer 1

當使用epydoc記錄多個文件時，此問題消失。這似乎是epydoc中的一個錯誤，但它很容易解決，只要你有一個實際的文件包，而不是一個單獨的模塊。