问题标签 [sphinx-napoleon]

我正在使用带有 sphinx.ext.autodoc 的 Google 样式的文档字符串来自动为我的函数生成文档，并确保它们在代码中正确地自我记录。

我有一个def myfunc(id=None, size=None, hash=None)基于id or size + hash返回信息的函数。如果我们有id作为论据size并且hash不需要，如果我们有size和hash作为论据，则id不需要。

使用 sphinx，可以指定一个可选参数，但在这种情况下，我们不知道什么是强制性的，什么是可选的。这是一个例子：

问题是：如何判断文档字符串中需要哪些参数？

您可以轻松地争辩说函数本身就是问题所在，即使结果相同，两个参数对也应该位于单独的函数中：

但在这种情况下，如果可能，最好使用单个函数，因为该函数是与另一个使用单个函数的 API 的绑定。

现在有没有人将现有项目中的所有文档字符串从重构文本转换为谷歌格式的简单方法？

看起来拿破仑可以做类似的事情，但看起来很复杂，所以我想我会问是否有人以前做过。任何想法将不胜感激。

我想知道如何实现以下目标。我将 numpy docstring 样式与 sphinx autodoc 结合使用来生成自动文档。但是，我正在努力在输出中有一个嵌套列表：

此文档字符串的输出已完成。它无法识别属性 1 的列表。

另一方面，功能描述跨越多行：

同样在这里 sphinx 不识别完整的功能，并独立于第一行处理第二行。

我的格式有什么问题？

我将 sphinx autodoc 扩展与 sphinx.ext.napoleon 一起使用。我正在关注 numpydoc 样式指南，因为我认为它比 google 的更具可读性。但是，我注意到以下我无法解决的问题。

我有以下问题。是否可以在参数部分（或返回等）中允许有一个列表？我想要类似的东西：

更新根据史蒂夫皮尔西的回答，我已经删除了一些初始问题。这是python文件：

不幸的是，这仍然给出了“这将是……”的字体太大并且没有放在param_1as for旁边的问题param_2：

如果我删除项目符号列表，我会得到一个外观正确的输出。将上面的代码更改为：

这导致以下正确的输出：

生成文档的 .rst 文件很简单：

如果我使用 numpydoc 而不是 sphinx.ext.napleon 似乎我得到了正确的输出：

至少“pandas data frame”和“This....”的字体是一样的。但是我更喜欢拿破仑风格，一切都更小，一开始没有灰线。

最后，在项目符号点之前删除空行也无济于事。它使情况变得更糟：

我目前正在尝试使用 Sphinx 实现自动文档创建（使用扩展 sphinx-apidoc 和拿破仑）。这工作得很好，但如果类型提示（PEP484 约定）自动添加到参数列表中会更好。

我想知道这是否可能。

更具体地说：（来自拿破仑的例子）

这呈现如下：

参数列表包含所有参数，但不附加类型。可以手动添加它们，但这可能会在决定更改签名时引入未来的问题。

手动类型添加示例：

呈现为：

我想从文档字符串自动生成文档到我的代码。我有一些用于存储一些数据的基本类：

我的rst文件：

我以不同的方式记录了每个属性以显示差异，这是输出：

似乎 Sphinx 无法将该Attributes部分与真实属性联系起来，这就是它无法显示其默认值的原因。

我想要实现的最终输出是version与定义为 for 的文档字符串的字段的结果batch。我想用默认值和类型显示属性名称，但取自类型注释。在这种情况下，Sphinx 似乎忽略了类型注释。

我的狮身人面像扩展：

我该怎么做才能实现这种行为？对于这种用例，我找不到任何好的例子。

我知道用于为 Google 样式构建文档字符串的语法，例如：

但是，如果我有一个函数可以根据执行的代码分支返回多种类型怎么办？什么是记录这一点的正确方法？

下面是一个例子。应该在零件中放入什么Returns？

有一个示例显示了两种不同的可能返回类型：

但是，我想知道提供两种类型和描述的最佳方式是什么，以便拿破仑支持它原生并且也很容易阅读文档。

使用int/str: %description%是处理多种返回类型的唯一方法吗？

我正在使用拿破仑语法为我的函数编写文档。我想在文档中的参数列表之后有一个段落。文档当前如下所示：

文档当前呈现（使用 RTD 主题）为

x(a)

一个示例函数。

之前的样本简介。

参数          * a ( str ) - 输入参数
                              * ( A )之后的段落-

我想看到的是

x(a)

一个示例函数。

之前的样本简介。

参数          * a ( str ) - 输入参数

后一段。

我如何告诉 sphinx/napoleon/rST 突破该Parameters部分？

我有一个mod带有一些子模块的模块submod并用于.. automodule:: mod.submod为其生成文档。

模块中元素（函数、类等）的签名现在显示限定名称，例如mod.submod.my_function(*args, **kwargs).

相反，我希望 Sphinx 只显示函数的名称，即签名my_function(*args, **kwargs)。

我有什么方法可以删除签名中的主要模块和子模块吗？

我正在使用 Sphinx 来记录一个 python 项目。我想在我的文档字符串中使用 Markdown 来格式化它们。即使我使用recommonmark扩展名，它也只涵盖.md手动编写的文件，而不是文档字符串。

我在我的扩展中使用autodoc,napoleon和。recommonmark

如何在我的文档字符串中制作 sphinx 解析降价？