Support Twisted's deprecatedModuleAttribute

[mthuurne]

Currently neither Twisted's customizations nor pydoctor supports Twisted's deprecatedModuleAttribute mechanism. There are about 40 uses of this mechanism in Twisted.

Assuming that we implement #315, it would be pydoctor's job to support this decorator.

deprecatedModuleAttribute can be used to deprecate modules within a package, for example twisted.python.constants and twisted.python.url are marked as deprecated in src/twisted/python/__init__.py.

deprecatedModuleAttribute can be used to deprecate aliases, for example the roughly 20 uses in src/twisted/python/compat.py are all on aliases. This means that until #313 is fixed, we don't have any place to put those deprecation notices on.

deprecatedModuleAttribute is sometimes used on classes, such as UsernameHashedPassword in src/twisted/cred/credentials.py. It is also possible to deprecate a class by decorating it with @deprecated; the difference is that deprecatedModuleAttribute warns as soon as the class is accessed, while @deprecated warns on instantiation. Sometimes deprecatedModuleAttribute is called after the class definition, sometimes it is called inside the class definition.

What I originally assumed to be the main use of deprecatedModuleAttribute is to deprecate constants, but this is a small minority of the uses I found. Deprecated constants do exist though, for example instance_atom in src/twisted/spread/jelly.py.