文档字符串未填充 Sphinx 文档答案

【问题标题】：Docstrings not populating Sphinx documentation文档字符串未填充 Sphinx 文档
【发布时间】：2021-12-25 01:49:24
【问题描述】：

我正在尝试为我的 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 中。

我正在使用...

Python 3.8
Sphinx 4.2（虽然我尝试过很多版本）
NumPy 文档字符串

我有……

添加了以下扩展
- sphinx.ext.autodoc
- sphinx.ext.apidoc
- sphinx.ext.napoleon
使用相对路径和绝对路径（相对路径为../MyCode）将conf.py 指向我的代码。

出于某种原因，我能用我的文档实际填充 HTML 页面的最接近方法就是将类放在索引 toctree 中。它们链接到没有我的 Python 文档字符串的空白 html 页面。

有谁知道为什么它不会抓取我的文档字符串？？

【问题讨论】：

这能回答你的问题吗？ Sphinx apidoc not automated enough
没有名为sphinx.ext.apidoc 的Sphinx 扩展（但有一个名为sphinx-apidoc 的命令行脚本：sphinx-doc.org/en/master/man/sphinx-apidoc.html）。

标签： python python-sphinx docstring

【解决方案1】：

好吧...对此感到很愚蠢，但这只是警告的原因。

Sphinx 要求该软件包是一个完全可安装的软件包，即当它被放入 sphinx 软件包时，它应该能够编译。我的导入语句中有一些绝对引用导致我的程序失败。因此，在我的 sphinx html 中仍然显示类的名称时，无法提取程序中的实际文档字符串。

基本上确保您的代码在尝试将其放入 Sphinx 时可以编译。

【讨论】：