问题标签 [autodoc]

Sphinx 文档引擎是否会成功地为一个不能很好导入的项目生成文档？特别是我的项目有一个异国情调的依赖。我不希望文档生成依赖于这种依赖关系。

Sphinx 需要导入我的模块并使用自省还是解析？

我有以下文档字符串：

如果可用，有没有办法告诉sphinx将“默认为 X”部分添加到参数的描述中？

我开始研究 python33 模块的文档。但我是这个领域的初学者。如果您能帮我选择好的仪器来做这件事，我将不胜感激。我在互联网上阅读了很多主题。我发现最受欢迎的是 sphinx 和 Epydoc。但是它们中的哪一个更好用？互联网上讨论的几乎所有问题都是相当古老的。我敢肯定，自 2011 年以来情况已经发生了变化。可能有人在为 python 文档做文档方面是专业的。请帮助迈出第一步。

我写了一个 python 类，并用 sphinx 制作了文档。例如，该类如下所示：

现在，为了做文档，在我写的第一个文件中：

一切正常，并且a和prop出现square在文档中。

但是如果我尝试分别记录属性和方法，sphinx 说它找不到属性 a，但它适用于 prop。

错误信息是：

我在某处读到了属性报告为 None 的 Sphinx 值，即 sphinx 不实例化类，因此类属性（作为道具）和实例属性（作为 a）之间存在差异。但是如何在文档中引用实例属性？

实际上，如果在 rst 文件中没有明确询问实例属性，则会找到它们。例如，这将起作用：

但这不

autodoc以下两个属性定义在 Sphinx HTML 输出中显示完全相同：

Sphinx 有办法用某种标识符注释抽象方法吗？我希望在我的文档中清楚地表明我的 ABC 的哪些成员需要实现，以及一旦定义了所需的那些是你得到的 mixin 免费赠品。

我正在尝试在 Sphinx 中使用 autodoc 打印出特定模块中每个函数的文档字符串，但不包括模块的文档字符串。可能吗？

原因是我使用模块文档字符串来指定命令行选项（使用可爱的文档）。

我们如何使用自动文档？

我为我的项目和它们的命名空间都做了 python setup.py 是可导入的..

我试过了：

但我只是得到

我做错了什么？

我正在开发一个只有一个 .py 模块的 Python 库，并且我正在尝试从文档字符串中为其生成文档。我已经设置了 Sphinx 并运行了 spinx-quickstart 脚本，但是当我尝试运行时（在 docs 目录中）

但它只是说：

是否有其他一些 Sphinx 脚本可以自动生成单个文件？我想过只是运行它，..但后来我想它会运行到我的测试目录并尝试从我的单元测试中生成文档......

这是我的文件层次结构：

信息救援
|
|_ 源
|
|_ _ _ 包括
|
|_ _ _ _ _ i1.py
|_ _ _ _ _ i2.py
|_ _ _ _ _ init .py
|
|_ _ _ 实用程序
|
|_ _ _ _ _ u1.py
|_ _ _ _ _ u2.py
|_ _ _ _ _ init .py
|
|_ _ _ 文档
|
|_ _ _ _ _ index.rst
|_ _ _ _ _ project.rst
|_ _ _ _ _ contact.rst
|_ _ _ _ _ api
|
|_ _ _ _ _ _ _ api.rst
|_ _ _ _ _ _ _ 包括.rst |_ _
_ _ _ _ _ utils.rst

我正在使用 Sphinx 生成文档。与 sphinx 相关的所有内容都在doc目录中。

我的 index.rst：

api.rst：

现在在 utils 里面有 .py 文件。这两个文件都不包含类和直接代码，都只包含函数。要记录我可以使用的功能.. autofunction:: utils.u1.functionName。这工作正常，但我必须为每个功能都这样写。有什么简单的方法可以简单地包含所有功能吗？

假设包含目录中的两个文件都不包含类，并且只包含一些（直接）代码。如何为其生成文档，即使用哪个自动指令？

此外，utils 和包含目录中的init .py 文件都是空的。我做了这两个，以便我可以从 .rst 文件访问这些目录中的文件。有没有其他方法可以让我不必创建 _ init _.py 文件？

这个问题的灵感来自Mayavi 文档，其中有很好的分节符，每个模块成员之间描述的函数名称。

我.rst现在看起来像：

（在模块本身中包含所有文档格式的文本。）

有没有一种简单的方法来表明我想在每个成员之间插入节标题:members:？如果没有，Mayavi 人是怎么做到的？