pydoctor's handling of duplicate names needs a rethink

[mwhudson]

Originally reported as Twisted issue 2621:

There are several cases, some of which get quite tricky. This is not an exhaustive list, but some examples are:

def foo(): pass
def foo(): pass

class B: pass
class B(B): pass

if quux:
def foo(): pass
else:
def foo(): pass

---

Imported from Launchpad using lp2gh.

• date created: 2009-08-06T18:48:42Z
• owner: exarkun
• the launchpad url was https://bugs.launchpad.net/bugs/410001

[tristanlatr]

Here is my proposition for tackle this issue:

For System.allobjects and for Documentable.contents, we adopt a version of dict that maintains a stack of duplicates objects, that we can request with special methods. Like this one: https://github.com/tristanlatr/pydocspec/blob/main/pydocspec/dupsafedict.py

• Duplicates classes/modules/package: they could be shown in the same page. It could be a bit weird, but it's better than the current behaviour.
• For cases where a Function or Attribute overrides a Module or a Class, I don't think it would be an issue to show the documentation properly and not having to rename anything, actually.

The HTML writer should be adapted such that it can show many classes/modules on the same page and iterates over all objects, including duplicates.