sphinx-doc / sphinx-doc/sphinx

autodoc pulls parent constructor docstring when subclass has its own constructor

Open
#8,233 1 comment 0 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

extensions:autodoc type:bug
Dominant language
Python
Stars
8k
Forks
2.6k
PR merge metrics
No merged PRs in 30d

Description

Describe the bug
When a sub-class defines an override for init, if a docstring isn't provided autodoc pulls the docstring from the parent class constructor. This doesn't make sense since the override can present a different set of arguments.

I'm guessing this behavior matches how function docstrings are inherited. For functions this behavior makes sense because, I think, modifying the function parameters on an override would violate the Liskov substitution principle. I don't think constructors are expected to comply with LSP as the idea is that a constructed subclass instance may by substituted for the base but how it is constructed may be changed.

To Reproduce
The following is an example class

class BaseClassHasInitDocString:
    """
    This base class properly documents ``__init__``
    """
    def __init__(self, param1: int, param2: str):
        """
        My constructor documentation

        :param param1: my int param
        :param param2:  my string param
        """

class SubClassOverridesButNoDocString(BaseClassHasInitDocString):
    """
    This sub-class overrides the constructor with different parameters but fails to provide a docstring.

    Parent constructor's docstring shouldn't be inherited here because an override exists
    """
    def __init__(self, param: bool):
        super(SubClassOverridesButNoDocString, self).__init__(5, "default string")

class SubClassHasNoConstructor(BaseClassHasInitDocString):
    """
    This sub-class doesn't override constructor.  Constructor documentation correctly matches parent class constructor
    """

The following options are in conf.py

# Custom theme from ReadTheDocs
html_theme = 'alabaster'

# options for autodoc
autodoc_default_options = {
    'member-order': 'bysource',
    'members': True,
    'undoc-members': True,
    'show-inheritance': True,
}
autodoc_typehints = 'signature'
autoclass_content = 'both'

This is the simple index.rst

Hello World
===========

code docs
=========

.. automodule:: helloworld.helloworld

Expected behavior
If constructor is overridden, docstring should match the overridden constructor even if it isn't explicitly provided.

Your project
Example provided above.

Screenshots
image

Environment info

  • OS: Ubuntu 20.04
  • Python version: 3.8.2
  • Sphinx version: 3.2.1
  • Sphinx extensions: sphinx.ext.autodoc
  • Extra tools:

Additional context
Add any other context about the problem here.

  • [e.g. URL or Ticket]

Contributor guide

Open the contributing guide

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

Research direction

Reproduce the behavior using the classes, conf.py, and index.rst example with the sphinx.ext.autodoc extension. Start by tracing how autodoc handles inherited constructor docstrings, then verify that an overridden constructor does not receive the parent docstring while a subclass without its own constructor still does.

Written by the indexing model from the issue text.

Assessment

Tech stack
python
Domain
documentation
Issue type
Bug
Difficulty
4/5
Estimated time
3-5 days
Activity status
Stale
Clarity
Mostly clear
Newbie friendliness
35/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.