List of class methods with Napoleon Sphinx extension using NumPyDoc style

Question

I am using NumPyDoc-style docstrings to document a Python package. I would like to switch from the 'numpydoc' Sphinx extension to Napoleon, because I find that it formats the docstring in a more compact and readable way. However, it does not list the methods of a class at the top of the documentation, which I find a very valuable feature of numpydoc. Does anyone know how to switch this on manually in Napoleon?

Answer 1

I am new to Napoleon/Sphinx, but I think the answer might be in Sphinx, rather than Napoleon.

If you have autodoc enabled in conf.py, eg.

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

then add to your index.rst (say):

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

where module_name contains the class in question, then class_name will be in the documentation along with all of its methods, even if they do not currently have a docstring.

Answer 2

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