问题标签 [numpydoc]

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

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

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

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

我正在使用 Sphinx+autodoc+autosummary 为我的项目 ( mrpy) 生成文档。

我正在做一个两层总结，其中index.rst我有（最少）

如您所见，我为模块级自动摘要使用了自定义模板。我这样做是为了在模块级摘要上，我还获得模块内对象的摘要，每个对象都链接到自己的页面。作为参考，我的modules.rst文件是

mrpy.stats仅包含三个类，当点击索引页面上生成的表格中的链接时，它们得到了很好的总结。当点击这些类之一的链接时，我使用了另一个自定义模板class.rst：

但是，该类的页面包含标题，如预期的那样，类文档字符串，如预期的那样，但是该类的方法和属性的两个列表摘要。

任何人都知道如何摆脱冗余表之一？

我无法使用 numpy 格式使 Sphinx 正常工作。我正在使用这个示例进行测试，执行“make html”，但我收到几个警告来识别参数、注释、返回等。例如：

已经问过这个问题，但是经过几个小时的搜索和尝试，我没有成功。

到目前为止我所做的：

• 安装狮身人面像 v1.3.5
• 更新numpydoc到版本 0.5
• 将扩展名numpydoc、、sphinxcontrib.napoleon和添加sphinx.ext.napoleon到conf.py文件中。
• 试过 rst2html docum.txt docum.html
• 因为我认为它没有使用 numydoc，所以我写了一个不正确的名称作为扩展名，它给出了一个错误（应该是这样，所以我认为它正在识别 numpydoc）。
• 添加numpydoc_show_class_members = False到conf.py
• 删除整个以前的 html 输出

有什么建议或提示有什么问题吗？我可以尝试什么？

谢谢

使用 autodoc 时是否可以禁用完整的自动摘要？

我有一个派生自Python 标准库类的类，它有许多公共方法。我的自定义类应该用作包装器，直接提供使用其协议与我的设备通信的方法。因此，我只想在自动汇总表中包含一些选定的继承方法。

该..autosummary::块完全符合我的要求，但..autoclass::会自动创建一个完整的方法表。有没有办法禁用此功能？

编辑（澄清）

直接使用autosummary指令，我可以生成一个只包含my_methodand的方法表another_method：

但是，当使用没有以下autosummary指令的autoclass或automodule 时，我仍然得到一个方法表，看起来与上面的autosummary块创建的方法表完全相同，只是描述了所有方法：

编辑 2

“完整”自动汇总表由numpydoc生成。

我正在尝试使用 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 一起提供。

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

这里的主要问题是哪里（如果）有一个objects.invfor TensorFlow，但是一个如何实际使用它的例子会很好。

例如，我目前有以下文档字符串：

如何使用 intersphinx 自动将对象链接到 TensorFlow 文档？

Question about numpydoc docstring conventions:

I have a class that contains a number of methods that return nothing, but add an attribute to the class. For example:

In this clumsy example, MyClass.a_mult doesn't return anything, but adds an attribute to MyClass.

I've included a docstring for MyClass.a_mult following the numpydoc style guide. The docstring states that the method returns None, but I can't see a standard way of documenting how the MyClass.a_mult method modifies the MyClass instance.

Thanks in advance for your help!

我想解析一个 numpydoc 文档字符串并以编程方式访问每个组件。

例如：

我想做的是：

我一直在四处寻找，发现了numpydoc和napoleon之类的东西，但我没有找到任何关于如何在我自己的程序中使用它们的好的线索。我会很感激任何帮助。

我正在使用带有 numpydoc 扩展和自动摘要的 sphinx。经过一些实验，我在我的 conf.py 文件中添加了以下选项。

这为我下面引用的每个类提供了一个新文件，它还创建了所有属性和方法的汇总表。

问题是，虽然在文档字符串的第一行有一个方法的汇总表，但方法的名称并没有链接到任何东西。如何获取方法的文档字符串以创建自己的文件（或至少在与类相同的文件中生成文档）？