文檔字符串未填充 Sphinx 文檔

Question

我正在嘗試為我的 Python 應用程序生成 Sphinx 文檔。 最初我有一個復雜的結構如下......

venv
docs
├───source
├───├───_static
├───├───_templates
├───├───conf.py
├───├───index.rst
├───├───modules.rst
├───├───...
├───build
├───make.bat
├───Makefile
├───MyCode
├───├───Utilities
│   │   └───class1.py
├───├───Configurations
│   │   ├───Archive
│   │   ├───API1_Configurations
│   │   │   ├───Config1.ini
│   │   ├───API2_Configurations
│   │   │   ├───Config2.ini
│   │   ├───API3_Configurations
│   │   │   ├───Config3.ini
│   │   ├───API4_Configurations
│   │   │   ├───Config4.ini
├───├───APIs
│   │   ├───API1
│   │   │   ├───Class1.py
│   │   │   ├───Class2.py
│   │   ├───API2
│   │   │   ├───Class1.py
│   │   │   ├───Class2.py
│   │   │   ├───Supporting
│   │   │   │   └───Class1.py
│   │   ├───API3
│   │   │   ├───Support
│   │   │   │   ├───SupportPackage1
│   │   │   │   ├───Support Package2
│   │   │   │   │   └───Class1.py
│   │   │   │   └───__pycache__
│   │   │   └───Class1.py

在這種情況下，我的源代碼存在於 ./docs/MyCode 中。

我在用...

• 蟒蛇 3.8
• Sphinx 4.2（雖然我嘗試過很多版本）
• NumPy 文檔字符串

我有...

• 添加了以下擴展
  • sphinx.ext.autodoc
  • sphinx.ext.apidoc
  • sphinx.ext.napoleon
• 尖conf.py我的代碼同時使用相對路徑和絕對路徑（相對路徑之中../MyCode ）。

出於某種原因，我最接近實際使用我的文檔填充 HTML 頁面的方法就是將類放在索引toctree 。 它們鏈接到沒有我的 Python 文檔字符串的空白 html 頁面。

有誰知道為什么它不會抓取我的文檔字符串？

Answer 1

好吧……對此感覺很愚蠢，但這只是警告的原因。

Sphinx 要求該包是一個完全可安裝的包，因為當它被放置在 sphinx 包中時，它應該能夠編譯。 我的導入語句中有一些絕對引用，這導致我的程序失敗。 因此，當類的名稱仍然顯示在我的 sphinx html 中時，無法拉出我程序中的實際文檔字符串。