问题标签 [autodoc]

我正在尝试使用 sphinx autodoc扩展，特别是automodule为我正在开发的 django 应用程序自动生成文档的指令。问题是我想在模块中创建对不同类的内部引用，而不必在项目中的每个类/函数上使用autoclass和。autofunction对于这样的源文件：

我希望能够拥有这样的 sphinx 文档文件：

我可以为 XXXX-some-reference-to-A-XXXX 使用什么参考？有没有简单的方法来实现这一点？在此先感谢您的帮助。

我想在我的 Sphinx 文档中只包含特定函数的文档字符串。但是，似乎没有选项可以使用http://www.sphinx-doc.org/en/master/usage/extensions/autodoc.html在没有关联的类和函数定义的情况下仅显示这些详细信息

我已经尝试创建一个类，如Show *only* docstring in Sphinx 文档中所述？但我不确定这如何适合模板。

我也尝试过 autodoc-process-docstring 事件处理程序，但没有成功。

因此，而不是我的文档显示（目前）：

我只想显示：

我当前在 .txt 文件中的模板是：

我正在使用 Sphinx autodoc 扩展来记录模块，并且我想在文档输出中获得模块成员的平面列表。

我尝试使用以下内容：

但是，这样做有两个问题：

1. 它包括模块的文档字符串，我不想在这里。

2. 每个条目的名称都以“modname.”为前缀，这是完全多余的（因为此页面专门用于记录此模块）

但是，我还没有找到任何配置选项，可以让我有选择地禁用这两个方面，同时仍然获得所有模块成员的自动列表。

我目前的计划是只使用自动功能（等）并明确枚举要记录的成员，但我仍然想知道我是否错过了实现我最初想要的简单方法。

更新：我至少找到了第二部分的解决方法：设置add_module_names=False在conf.py. 不过，这是一个全局设置，所以它并不能真正回答我原来的问题。

是否可以使用 Sphinx autodoc 从函数 docstrings 为我的 fabfile 生成文档？

setup_development例如，对于包含我尝试过的任务的 fabfile ：

但是什么也没有产生。

fabfile 片段：

我有这个 Cython 课程：

我希望 Sphinx 像这样记录它：

类 Sprite ( self, texture )
    做事。

所以我尝试记录它：

但它甚至没有出现。我什至试过这个：

这一次它确实出现了，但 sphinx 并没有像往常那样用这些信息做神奇的事情：

class Sprite
    Sprite(self, texture)

    做事。

那么我该怎么做呢？

当我使用 Sphinx autodoc 来记录一个类时，属性的值总是被报告，（正如它所说的应该在这里，在 #437 下）但总是作为“= None”

我把它包括在内

我的代码看起来像

有没有办法让“= None”报告真正的价值，或者让它消失？

我正在尝试开始使用 Sphinx 来记录我的一些小项目，但似乎我无法让它工作。

我已经四处搜索，但到目前为止我尝试的一切都没有解决导入错误。

这正是我正在做的事情：

我也试过这个：

输出看起来令人鼓舞，但实际上如果我打开 index.html，按 Title 测试模块的页面是完全空白的。它只是有标题，没有文档字符串或其他任何东西。

有谁知道我在这里做错了什么？我认为放置 .. automodule + .. autoclass 会自动显示这些文档字符串，但我看不到它们。

编辑：

修复了，但我不明白为什么......这是我这次做的（我认为它和以前完全一样）

顺便说一句：很抱歉有很多行代码。

编辑2：

我发现如果我清除 build/html 目录，autodoc 不会显示任何错误，但为模块生成的文件是空白的。没有显示文档字符串（即使在我说它已修复之前，文档字符串已正确显示......）。

如果我将空文件夹 _sources 和 _static 留在 build/html 文件夹中，则 autodoc 将找不到模块。

真的，我不明白发生了什么。

编辑 3：

好的，现在这很疯狂：

似乎该程序不是确定性的，而是随机“工作”（模块文档文件仍然为空）。

现在我开始认为改变软件可能会更好。

编辑4：

我重写了其中一个模块，现在 autodoc 可以完美运行...但是我没有更改任何模块中的任何导入（我认为这可能是我的模块的错），所以我对结果的这些变化感到非常困惑。

很抱歉写了这么长的问题没有答案。无论如何，我仍然期待有人知道发生了什么。

我正在尝试开始使用 Sphinx，但似乎遇到了无情的问题。

命令：docs/sphinx-quickstart

我回答了所有问题，一切正常。

命令：docs/ls

一切看起来都很正常。结果：build Makefile source

命令：sphinx-build -d build/doctrees source build/html

它似乎工作。我能够打开 index.html 文件并看到我想要的“外壳”。

当我尝试将我的实际源代码作为source文件夹时，我遇到了问题。

命令：sphinx-build -d build/doctrees ../ys_utils build/html

结果：

我是 Sphinx 的新手，对这类文档也比较陌生。任何人都可以提供一些建议吗？

编辑：

我希望能够使用 Makefile 来处理这个问题。截至目前，我的项目中有两个文件夹。

nextgen/ls

docs ys_utils

我需要为我将拥有nextgen/docs/Makefile的所有其他模块生成 HTML 。ys_utils

CPython 的文档不使用自动文档——我们使用手写的散文。

对于 PEP 3144（ipaddress 模块），我想使用 sphinx-apidoc 生成初始参考文档。这意味着我想运行两次操作：

1. 使用 sphinx-apidoc 为依赖于 autodoc 的模块生成一个 Sphinx 项目

2. 运行创建新的 reStructuredText 源文件的 sphinx 构建器，所有 autodoc 指令被内联 reStructuredText 内容和产生相同输出的标记替换

第一步很简单，但我不知道如何进行第二步，甚至想不出好的方法来搜索任何现有的项目。

我正在开发一个 python 库，我正在使用sphinx.autodoc来生成文档，因为我认为这是一个不要重复自己并且让文档和代码达成一致的好方法。

在sphinx autodoc 对 Emit reStructuredText 的评论中？我了解到“CPython 文档构建过程没有启用自动文档（通过深思熟虑的选择）”。

我想知道为什么 CPython 不使用它，使用它有什么缺点sphinx.autodoc？