pdoc3 / pdoc3/pdoc

Inherited class with overwritten method is not working as advertised in the doc

Open
#75 4 comments 0 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

Dominant language
Python
Stars
1.2k
Forks
146
PR merge metrics
No merged PRs in 30d

Description

Expected Behavior

The doc says :

pdoc considers methods' docstrings inherited from superclass methods', following the normal class inheritance patterns. Consider the following code example:

>>> class A:
...     def test(self):
...         """Docstring for A."""
...         pass
...
>>> class B(A):
...     def test(self):
...         pass
...
>>> A.test.__doc__
'Docstring for A.'
>>> B.test.__doc__
None

In Python, the docstring for B.test doesn't exist, even though a docstring was defined for A.test. When pdoc generates documentation for the code such as above, it will automatically attach the docstring for A.test to B.test if B.test does not define its own docstring. In the default HTML template, such inherited docstrings are greyed out.

So I expect to see "test" in the methods of B, documented with the docstring of A.

Actual Behavior

In my tests with pdoc3 v0.5.0 to v0.6.2, I don't see "test" in the methods of B. It says it is inherited. It is in reality not the case as it is overwritten.

When I add a docstring to B.test, it reappears in the methods of B.

Steps to Reproduce
  1. Create this file main.py :
class A:
    def test(self):
        """Docstring for A."""
        print("From A")


class B(A):
    def test(self):
        print("From B")
  1. Run pdoc --html
  2. Open the generated doc and remark that B.test is not listed in the method, as pdoc thinks it is inherited, which it is not.
Additional info
  • pdoc version: 0.5.0, 0.6.0, 0.6.1, 0.6.2

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

Start with the main.py reproduction and run pdoc --html using the reported versions or the current package. Inspect how generated documentation decides whether B.test is inherited, then compare B's method listing with the expected inherited docstring behavior. Done means B.test appears in the generated methods with A.test's docstring when B.test has no docstring.

Written by the indexing model from the issue text.

Assessment

Tech stack
python
Domain
documentation
Issue type
Bug
Difficulty
3/5
Estimated time
1-2 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.