问题标签 [sphinx-napoleon]

sphinx-doc napoleon Google style docstrings example here for version 1.3.4 显示函数/方法的可选参数应记录如下：

但是这里1.4a0 版本的同一页面显示了以下方式来做同样的事情：

但是我在文档中没有看到对这种新语法的任何解释。我在哪里可以找到有关 Google 样式文档字符串中支持的新语法的更多信息，其中包含 sphinx-doc 的拿破仑扩展？

我想__init__()在我的 sphinx 生成的文档中包含文档字符串。

我正在按照这个 stackoverflow 问题的公认答案添加处理程序，autodoc-skip-member但仍然无法看到我的__init__()文档。块内的跟踪代码if name == "__init__":显示我正在点击该代码。

凭直觉，我'sphinx.ext.napoleon'从我的extensions定义中删除，离开

然后我可以看到__init__()文档。

我在拿破仑文档中看到的唯一似乎相关的是napoleon_include_special_with_doc，它说默认为True. 将其显式设置为Trueinconf.py似乎并没有改变任何东西。

ETA：如果我添加以下方法：

我__blah__()在我生成的文档中看到。

• 如果我将名称更改__blah__为__repr__或__str__，我会在生成的文档中看到它们。
• 如果我注释掉现有的__init__并更改 __blah__为__init__我看不到它。

所以它似乎特定于__init__().

这是一个已知问题吗？在使用拿破仑时是否有另一种方法来控制它？

我正在尝试使用 Sphinx 1.4 和扩展为我的 python 类生成sphinx-apidoc文档sphinx.ext.autodoc。

我有很多模块，我希望每个模块只显示类名，而不是类中方法的完整列表（在我的代码中都有文档字符串）。

这是我的conf.py文件的片段：

这是一个玩具模块 ( my_module.py)，我用它来了解 Sphinx 的工作原理：

我只显示这个类的代码，以防我需要在我丢失的文档字符串中做一些事情。

我运行 sphinx-apidoc 来生成 rst 文件：

sphinx-apidoc -f -M -e -o docs/ /blah/sphinx/src/

然后构建：

制作html

我可能不清楚autodoc_default_flags应该做什么。我认为当您在设置了这些标志的情况下运行 sphinx-apidoc 时，这些标志将应用于 .rst 文件中的指令。但是，在我运行 sphinx-apidoc 之后，我得到了这个 .rst 文件：

由于设置了这些标志，我没想到:members:会被应用，但它确实存在！并且 html 页面具有完整的方法及其文档字符串。

FWIW，autodoc_member_order正在工作；我可以设置它来切换方法出现的顺序。

所以我的问题：

1. 应该做我autodoc_default_flags所描述的还是我误解了它？
2. 如果它可以用来自动隐藏构建中的成员，我是否正确使用它？如果是这样，关于为什么我仍然被:members:添加到 .rst 文件中的任何想法？
3. 如果我误解了它，那么它到底有什么作用？以及如何自动从我的构建中隐藏方法文档字符串？

理想情况下，我想要像 SciPy 这样的东西，例如这里：

http://docs.scipy.org/doc/scipy/reference/cluster.hierarchy.html

为此，我正在玩拿破仑和 sphinx.ext.autosummary 扩展，但似乎只有 apidoc 应该能够隐藏类方法文档。

我正在使用Numpy 样式的 docstrings为 Python 项目编写文档。

numpydoc和napoleon是两个 Sphinx 扩展，它们解析 Numpy 样式的文档字符串以生成文档。第一个用于 Numpy 项目本身，第二个与 Sphinx 一起提供。

使用一个扩展而不是另一个的优点和缺点是什么？

我正在为遵循本指南的 python 项目编写文档：

http://sphinxcontrib-napoleon.readthedocs.io/en/latest/example_google.html

确切地说，指南的这一部分：

该Returns部分支持任何 reStructuredText 格式，包括文字块::

我的代码如下所示：

对于 sphinx 1.3.5-1.3.6，它按预期工作。

对于 sphinx 1.4.0-1.4.1 它会抛出这样的错误：

我使用 Sphinx 和 Napoleon 以及 autodoc 扩展来记录一个 Python 项目，以解析 Google 样式的文档字符串。由于 Google 风格涉及指定参数的类型，Sphinx 会自动创建指向标准库中标准类型文档的链接。Intersphinx 但是，默认情况下它链接到文档的 2.7 版本，而我想链接到 3.x 版本。我该如何控制这种行为？

当使用带有 google docstrings 的 Napoleon（我没有测试过 numpy，但我怀疑有类似的问题）并将napoleon_use_ivar选项设置为 时True，它会创建指向实例变量名称的链接。这些名称显然很常见（例如“名称”），并且将它们链接到一些随机定义没有帮助 - 有什么方法可以禁用它吗？

给定以下文档字符串：

它将尝试name在 html 输出中进行交叉引用。考虑到目标的模糊性，它抱怨这一点：

但是，它仍然会在 HTML 输出中创建一个链接——如果您单击该name属性，它会愉快地将您发送到一些与当前属性无关的随机符号。有没有办法禁用这种行为？

如果napoleon_use_ivar设置为False这不会发生，但属性输出一点也不紧凑，而且很难阅读。

这不是拿破仑特有的 - 如果您手动指定属性，ivar它还会以您无法控制的方式交叉引用它们：

那仍然有一个链接name。

我正在使用 NumPyDoc 样式的文档字符串来记录 Python 包。我想从'numpydoc' Sphinx 扩展切换到Napoleon，因为我发现它以更紧凑和可读的方式格式化文档字符串。但是，它并没有在文档顶部列出类的方法，这是我发现 numpydoc 的一个非常有价值的特性。有谁知道如何在拿破仑中手动打开它？

我正在尝试使用带有autodoc和拿破仑扩展的Sphinx为我的 Django 项目自动生成文档。

使用sphinx-quickstart我创建了以下结构：

我已经定制docs/source/conf.py以反映我的项目结构。

然后我转到项目的根目录并运行sphinx-apidoc -f -o docs/source .. 这会将.rst每个模块的文件添加到docs/source.

最后我去MyDjangoProject跑步make html。这失败，每个模块都有一个错误说

我究竟做错了什么？

我最近开始向我的项目添加文档，并且正在尝试遵循 Google 样式指南。我正在使用 Sphinx 生成文档，并使用 Sphinx 扩展名拿破仑来弥合 Google 样式指南和 reST 之间的差距。

我在渲染参数和注释时没有问题，但我似乎无法让示例部分呈现代码片段。

我还尝试了示例部分的双冒号。