Docstring for groups of methods in sphinx

Question

Is it possible to add docstrings for groups of methods in the Sphinx generated documentation?

For example, I would like to have something like:

class MyClass():
    """Doc of the class"""
    def __init__(self):
        pass

    """----- The following part is about imports -----"""

    def import_from_source_1(self):
        """Doc of import_from_source_1"""
        pass

    def import_from_source_2(self):
        """Doc of import_from_source_2"""
        pass

    """----- The following part is about exports-----"""

    def export_to_dest_1(self):
        """Doc of export_to_dest_1"""
        pass

    def export_to_dest_2(self):
        """Doc of export_to_dest_2"""
        pass

And the expected output would be:

MyClass
    Doc of the class

----- The following part is about imports -----
import_from_source_1
    Doc of import_from_source_1

import_from_source_2
    Doc of import_from_source_2

----- The following part is about exports-----
export_to_dest_1
    Doc of export_to_dest_1

export_to_dest_2
    Doc of export_to_dest_2

Note that my goal is not (only) to group methods (as found in Group method docstrings in sphinx ), but to add a docstring to the group.

Answer 1

A docstring is a string literal that occurs as the first statement in a module, function, class, or method definition ( https://python.org/dev/peps/pep-0257/#id15 ). You cannot have "extra" docstrings like the ones in the question.

However, you can do the grouping by using automethod :

.. currentmodule:: mymodule

.. autoclass:: MyClass

   The following part is about imports

   .. automethod:: import_from_source_1
   .. automethod:: import_from_source_2

   The following part is about exports

   .. automethod:: export_to_dest_1
   .. automethod:: export_to_dest_2