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

Question

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

Answer 1

sphinx.ext.autosummary helps to achieve a Sphinx table of contents for the lists of class methods and attributes

I went through both the numpydoc and Sphinx documentation to understand how it works. Do find the details below.

SECTION 1 : understanding working of numpydoc

Numpydoc documentation provides an explanation how the table of all class methods is implemented by default. It internally uses sphinx.ext.autosummary and numpydoc_class_members_toctree

• when numpydoc is added to extensions option in conf.py, sphinx.ext.autosummary will automatically be loaded as well.

• The following configurations options are True by default in numpydoc

  numpydoc_show_class_members = True #shows all members of a class in the Methods and Attributes 
  numpydoc_show_inherited_class_members = True #shows all inherited members of a class 
  numpydoc_class_members_toctree = True #creates a Sphinx table of contents for the lists of class methods and attributes. 
  

SECTION 2 : implementation with Sphinx extensions

Sphinx extensions : To implement table of all class methods, use autosummary along with autodoc extensions

Napolean documentation quotes

Napoleon interprets every docstring that Sphinx autodoc can find, including docstrings on: modules, classes, attributes, methods, functions, and variables

That is sphinx.ext.napoleon works along sphinx.ext.autodoc

1. First step is to explicitly include both sphinx.ext.autodoc and sphinx.ext.autosummary when you include sphinx.ext.napoleon in extensions option in your Sphinx conf.py

   extensions = [
     'sphinx.ext.autodoc',  # Core Sphinx library for auto html doc generation from docstrings
     'sphinx.ext.autosummary',  # Create neat summary tables for modules/classes/methods etc    
     'sphinx.ext.napoleon', # Support for NumPy and Google style docstrings  
   ] 
   

2. Second steps is to select directive and relevant options, autodoc documentation provides 3 directives automodule, autoclass and autoexception to document a module, class or exception respectively

   .. autoclass:: Noodle       
      :members:    #option to generate document for the members of the target module, class or exception
      :undoc-members:      #option to generate document for the members not having docstrings
      :inherited-members:  #option to include members inherited from base classes
      :private-members:    #option to generate document for the private members
      :special-members:  #option to generate document for the special members (like __special__)
   

   If you want set the above options as default in autodoc, you can set them in autodoc_default_options as mentioned in this documentation

      autodoc_default_options = {
          'members': True,
          'imported-members': True,
          'undoc-members': True,
      }
   

   Other supported options are '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'

3. Third and final step to set relevant options, autosummary documentation generates autodoc summaries i.e., function/method/attribute summary lists

   .. autosummary::
      :toctree: DIRNAME              #example from documentation
   
      sphinx.environment.BuildEnvironment
      sphinx.util.relative_uri
   

   The autosummary directive can also optionally serve as a toctree entry for the included items. Optionally, stub .rst files for these items can also be automatically generated when autosummary_generate is True.

   The following configuration options should also be set in your Sphinx conf.py:

   # generate autosummary even if no references
   autosummary_generate = True
   autosummary_imported_members = True
   

Answer 2

我是拿破仑/狮身人面像的新手，但我认为答案可能在狮身人面像，而不是拿破仑。

如果您在 conf.py 中启用了自动文档，例如。

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

然后添加到您的 index.rst （比如说）：

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

wheremodule_name包含有问题的类，然后class_name将连同它的所有方法一起出现在文档中，即使它们当前没有文档字符串。