Search code examples
documentationpython-sphinxpython-modulepython-packaging

Custom module name is not displayed with autoclass


I am building docs with sphinx and one of my .rst files has the following content:

############
Internal API
############

.. autoclass:: Individual::Individual
    :noindex:
    :special-members:
    :exclude-members: __weakref__
    :member-order: bysource
    :members:

.. autoclass:: exceptions::Error
    :noindex:
    :special-members:
    :exclude-members: __weakref__
    :member-order: bysource
    :members:

.. autoclass:: exceptions::IncorrectValueError
    :noindex:
    :special-members:
    :exclude-members: __weakref__
    :member-order: bysource
    :members:

The build is successful, but please take a look at the attached screenshot: pic

The problem is that the Individual class is properly prefixed with Individual module name whereas the two latter classes which reside in exceptions.py - are not. Why is this happening and how should I fix it?

Edit: I add the contents of my conf.py below (without unnecessary parts):

import os
import sys
import sphinx_rtd_theme
sys.path.insert(0, os.path.abspath('../moranpycess'))
extensions = [
    'sphinx.ext.napoleon',
    'sphinx_rtd_theme',
    'recommonmark',
]
templates_path = ['_templates']
exclude_patterns = ['_build', 'Thumbs.db', '.DS_Store']
html_theme = 'sphinx_rtd_theme'
html_show_sourcelink = False
html_static_path = ['_static']

As well as the contents of exceptions.py

class Error(Exception):
    """Base class for other exceptions.

    Args:
        Exception (Exception): built-in Exception class
    """

    pass

class IncorrectValueError(Error):
    """Handling incorrect values of user's arguments.

    Args:
        Error (Error): Base class for other exceptions.
    """

    def __init__(
        self,
        parameter,
        message="Please check the documentation for expected argument values.",
    ):
        """Class initializer.

        Args:
            parameter (str): parameter name
            message (str, optional): error message.
                Defaults to "Please check the documentation
                for expected argument values.".
        """
        self.parameter = parameter
        self.message = message
        super().__init__(self.message)

    def __str__(self):
        """Display the error message.

        Returns:
            str: error message
        """
        return f"Incorrect value for {self.parameter}. {self.message}"

Solution

  • This was indeed a special case of a reserved name in sphinx:
    https://github.com/sphinx-doc/sphinx/issues/9280

    It shall be fixed in the new release.