使用NumPyDoc样式的带有Napoleon Sphinx扩展的类方法列表

Question

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

Answer 1

sphinx.ext.autosummary帮助实现类方法和属性列表的Sphinx目录

我仔细阅读了numpydoc和Sphinx文档以了解它是如何工作的。一定要找到下面的详细信息。

第1部分：了解numpydoc的工作原理

Numpydoc 提供了默认情况下如何实现所有类方法的表的说明。它在内部使用sphinx.ext.autosummary和numpydoc_class_members_toctree

• 将numpydoc添加到conf.py中的扩展选项时，也会自动加载sphinx.ext.autosummary。

• 默认情况下，以下配置选项在numpydoc中为True

numpydoc_show_class_members = True #显示方法和属性中类的所有成员numpydoc_show_inherited_class_members = True #显示类的所有继承成员numpydoc_class_members_toctree = True #为类方法和属性列表创建一个Sphinx目录。

第2节：使用Sphinx扩展实现

Sphinx扩展：要实现所有类方法的表，请结合使用autosummary和autodoc扩展

Napolean documentation引文

Sphinx Napoleon解释

autodoc能够找到的每个文档字符串，包括模块、类、属性、方法、函数和变量上的文档字符串

也就是说，sphinx.ext.napoleon在sphinx.ext.autodoc上工作

1. 第一步是在Sphinx 中包含sphinx.ext.napoleon in extensions选项时，显式包含sphinx.ext.napoleon和sphinx.ext.autosummary

extensions = 'sphinx.ext.autodoc'，# Core Sphinx库用于从文档字符串‘sphinx.ext.autosumary’自动生成html文档，#为模块/类/方法创建整洁的汇总表'sphinx.ext.napoleon'，#支持NumPy和谷歌风格的文档字符串

1. 第二步是选择指令和相关选项，autodoc documentation提供了自动模块、自动类和自动异常三个指令来分别记录模块、类或异常

。。autoclass:：Noodle : members：#为目标模块的成员生成文档的选项，class或exception :undoc- members：#为没有文档字符串的成员生成文档的选项: inherited members：#包含从基类继承的成员的选项: private - members：#为私有成员生成文档的选项: special - members：#为特殊成员生成文档的选项(如__special__)

如果您想在autodoc中将上述选项设置为默认值，您可以在autodoc_default_options中将它们设置为mentioned in this documentation

autodoc_default_options ={ 'members'：True，'imported-members'：True，'undoc-members'：True，}

其他支持的选项有'members‘、'member-order’、'undoc-members‘、'private-members’、'special-members‘、’inherited members‘、'show-inheritance’、'ignore-module-all‘、'imported-members’、'exclude-members‘、'class-doc-from’、'imported-members‘、'class-doc-from'

1. 设置相关选项的第三步也是最后一步，autosummary documentation会生成自动文档摘要，即函数/方法/属性摘要列表

。。autosummary :toctree: DIRNAME # documentation sphinx.environment.BuildEnvironment sphinx.util.relative_uri中的示例

autosummary指令还可以选择性地用作所包括项的目录树条目。或者，当autosummary_generate为True时，也可以自动生成这些项目的存根.rst文件。

还应该在您的Sphinx conf.py中设置以下configuration选项

生成自动摘要，即使没有引用autosummary_generate = True autosummary_imported_members = True

Answer 2

我是第一次接触拿破仑/斯芬克斯，但我认为答案可能在斯芬克斯，而不是拿破仑。

如果您在conf.py中启用了autodoc，例如

extensions = ['sphinx.ext.autodoc',
    'sphinx.ext.napoleon',
    'sphinx.ext.coverage']

然后添加到你的index.rst中(比如)：

.. autoclass:: module_name.class_name
    :members:
    :undoc-members:

如果module_name包含有问题的类，那么class_name将与它的所有方法一起出现在文档中，即使它们当前没有文档字符串。