sphinx-autoapi fails to combine class and __init__ docstrings (autoapi_python_class_content = 'both')

Question:

sphinx-autoapi allows to combine the class docstrings and the __init__ docstrings using the autoapi_python_class_content = 'both' option.

However, even with this option set (conf.py), it fails to properly combine the docstrings:

The class SingleOutputEcospold2Importer

class SingleOutputEcospold2Importer(LCIImporter):

    """
    Class for importing single-output ecospold2 format LCI databases.

    Raises
    ------
    MultiprocessingError
        If an error occurs during multiprocessing.
    """

    format = u"Ecospold2"

    def __init__(
        self,
        dirpath,
        db_name,
        extractor=Ecospold2DataExtractor,
        use_mp=True,
        signal=None,
    ):

        """
        Initializes the SingleOutputEcospold2Importer class instance.

        Parameters
        ----------
        dirpath : str
            Path to the directory containing the ecospold2 file.
        db_name : str
            Name of the LCI database.
        extractor : class
            Class for extracting data from the ecospold2 file, by default Ecospold2DataExtractor.
        use_mp : bool
            Flag to indicate whether to use multiprocessing, by default True.
        signal : object
            Object to indicate the status of the import process, by default None.
        """

is rendered as

enter image description here

Asked By: Wasserwaage

||
Source

Answers:

The autoapi_python_class_content = 'both' option is fairly simple: it literally just concatenates two (normalized) strings. In the current case, the concatenation just continues the list of exceptions where it left off, because there’s no division between it and the "header" for the __init__ method.

The solution is to ensure that the concatenation results in the single string you want. This means modifying one (or both) strings in a way that you wouldn’t if you weren’t planning on them to be concatenated, but I don’t think that’s avoidable.

Here, you can add a blank line to the end of the class docstring to "terminate" the exception list explicitly, rather than simply letting the string end.

class SingleOutputEcospold2Importer(LCIImporter):

    """
    Class for importing single-output ecospold2 format LCI databases.

    Raises
    ------
    MultiprocessingError
        If an error occurs during multiprocessing.

    """

    format = u"Ecospold2"

    ...
Answered By: chepner