问题标签 [sphinx-napoleon]

我正在尝试使用 Sphinx 为大型 python 代码库自动创建 api 文档。

我尝试过使用 build_modules.py 和 sphinx-apidoc。使用任何一个，我都可以在我的输出目录中为包和顶级模块成功创建第一个文档。

但是，当我使用

它给出了数千个这种类型的错误：

对于代码库中的每个类和方法。通过一些实验，我想我发现 autosummary/autoclass 指令正在创建期望每个类和方法都有 rst 文件的目录树。

除了警告之外，文档似乎运行良好，但我想摆脱它们，我想我可能配置错误。

我也尝试过nipype/tools来达到同样的效果。

我修改了 apigen.py和build_modref_templates.py来为这些“缺失”的每个文档创建第一个存根，并根据需要使用 autoclass/autofunction/automethods。但是，构建需要相当长的时间（10 分钟），最终由于最后构建步骤中的内存错误而崩溃。

这是一个创建所有警告的示例模块 rst 文件：

感谢您提供有关如何解决这些警告的任何建议！我想远离任何涉及修改 sphinx 站点包文件的解决方案。

PyCharm 2.7（或 PyCharm 3）是否支持自定义 docstring 和 doctest 存根？如果是这样，如何编写这种特定类型的自定义扩展？

我当前的项目已标准化使用 Google Python 样式指南 ( http://google-styleguide.googlecode.com/svn/trunk/pyguide.html )。我喜欢 PyCharm 的 docstring 支持，但现在只有两种支持的格式是 epytext 和 reStructureText。我想要并且愿意自己编写一个 PyCharm 插件，它可以创建一个以 Google 或 Numpydoc 样式（https://pypi.python.org/pypi/sphinxcontrib-napoleon/）格式化的文档注释存根。这里特别重要的是将 PyCharm 具有的类型推断能力与其他两种文档类型结合起来。

我一直在阅读Numpy 的文档标准，它似乎没有提到对象属性——只有类属性。

那么，例如，我将如何记录以下内容？

编辑：只是想注意我正在切换到Napoleon，它说它支持属性，但不具体是类或实例属性。

我正在尝试使用 Google 代码样式来记录一个函数，然后我使用带有拿破仑扩展的 sphinx 来为其创建文档。该函数的不寻常之处在于它返回两个参数。我不认为拿破仑能解决这个问题。如果是这样，有人可以告诉我他们是如何处理的吗？

也许我收到一条消息，返回多个参数不是很好的编码风格，但你能做到吗？生成的 html 将这两行视为一个参数描述的一部分。如果我在服务器和 msg 行之间添加一个换行符，它会有所帮助，但它仍在记录一个 arg。

这个问题与另一个有关。建议和接受的解决方案是：

这个解决方案不起作用，至少对我来说。不解析带有arg1和描述的缩进子块。arg2

sphinx我应该如何使用,sphinx.ext.napoleon和 Google Style 文档字符串管理多个退货？

我尝试使用具有活动性和描述性的函数名称，然后用活动和描述性文本 (!) 对其进行记录。这会生成看起来冗余的代码。

python 中的简化（但不是那么不切实际）示例，遵循 numpy docstring 样式：

特别是对于 python，我已经阅读了PEP-257和 sphinx/napoleon 示例numpy和 Google 风格的文档字符串。我喜欢我可以为我的函数自动生成文档，但是对于像上面这样的冗余示例，“最佳实践”是什么？不应该简单地记录“明显”的类、函数等吗？“显而易见”的程度当然会变得主观......

我想到了开源的分布式代码。多位作者建议代码本身应该是可读的（calculate_inverse(A)优于dgetri(A)），但多个最终用户将从 sphinx 样式的文档中受益。

我正在为 Python 2.7 项目使用autodoc和napoleon. 在我想用一个automodule::指令记录的一个模块中，我有一个要应用:special-members:标志的特定类。标记automodule::with会显示模块中所有内容:special-members:的特价，这不好。

我怎样才能做到这一点？

添加autoclass::标记为 的指令:special-members:仍会将“非专业”文档作为automodule::内容的一部分保留在那里，从而导致内容重复。

我想我可以在 的:members:指令中明确键入模块中的所有类，但我的特殊目标类除外automodule::，但是我必须记住每次在模块中添加或删除一个类时更新该列表。

如何使用 Sphinx-Napoleon 在 Google 样式的文档字符串上为生成器指示列表类型、可选参数和返回类型？

我试过了

和

分别; 但都产生不令人满意的输出，与生成的文档的其余部分不一致。例如

只是给

可选[类型]

没有任何链接type。

我已经尝试了每个内置主题并且遇到了同样的问题。

我应该如何使用带有 Sphinx-Napoleon 的 Google 风格的文档字符串来记录这些元素？

有时 Python 中的函数可能会接受灵活类型的参数。或者它可能返回一个灵活类型的值。现在我不记得这样的函数的一个很好的例子了，因此我用下面的玩具例子来演示这样的函数可能是什么样子。

我想知道如何使用 Sphinx 文档符号为此类函数编写文档字符串。在下面的示例中，参数可能是str或int。同样，它可能会返回str或int。

我已经给出了一个示例文档字符串（包括默认的 Sphinx 表示法以及 Sphinx 的拿破仑扩展所理解的 Google 表示法）。我不知道这是否是记录灵活类型的正确方法。

狮身人面像默认符号：

狮身人面像拿破仑谷歌符号：

在要由 Sphinx 处理的文档字符串中表达参数或返回值的多种类型的正确方法是什么？

我正在编写一个 Python API，并且我使用Google 文档字符串约定记录了源代码中的每个类和函数，我发现它比 Sphinx 约定更具可读性。我想使用 Sphinx 为我的 API 构建文档。有一个名为Napoleon的扩展程序支持Numpydoc和Google 文档字符串，所以我尝试使用它，但遇到了几个问题。我在 Ubuntu 12.04 上使用 Python 2.7.3。

我安装了 Sphinx 1.1.3。我为文档做了第一步（sphinx-quickstart,autodoc启用了和一个 make 文件）。我在 Sphinx 1.3 之前读到过，我必须在我的文档中添加sphinxcontrib.napoleon作为扩展名。conf.py我这样做了，并得到了napoleon无法找到扩展名的错误。我下载了它，安装了它，然后我遇到了找不到某个包的错误：

无法导入扩展 sphinxcontrib.napoleon（例外：无法导入名称六）

这是需求文件中一个包的名称，所以我安装了它。我对另一个软件包有同样的错误，我也安装了它。现在我有同样的错误，但有“范围”：

无法导入扩展 sphinxcontrib.napoleon（例外：无法导入名称范围）。

我不知道它是哪个包裹，我在任何地方都没有找到它，所以我被卡住了。为了以防万一，我尝试了“sphinx.ext.napoleon”，但它找不到扩展名，这是预期的。

我想尝试使用 Sphinx 1.3 和应该与 Sphinx 一起提供的“sphinx.ext.napoleon”。使用 apt-get 安装时，即使在更新后，我也只能获得 1.1.3 版本。所以我尝试直接下载并安装Sphinx 1.3，但出现以下错误：

似乎是 setuptools 的问题。我找到了这篇文章并尝试了解决方案，但我无法让它工作。

我知道我可以更改我所有的文档字符串，但这需要时间并且可读性较差。我可以尝试除 Sphinx 之外的其他东西，但 Sphinx 是 Python 最常见的文档工具，这就是我尝试坚持使用它的原因。

如何从我的来源中的Google 文档字符串中获得一个好的文档（仍然是自动的）？