Show decorator and link to it?

[johann-petrak]

Pydoc currently does not indicate in any way that a function or other object has a decorator. But decorators are
often used to change or add to the way how a e.g. a function can be used by the API user. So documenting this is very important.

Ideally the generated documentation would show the decorator as in the source and allow to link to the documentation of the decorator implementation.

Documenting this manually for each function can be very repetitive when the same decorator is e.g. used for a large number of class methods.

[kernc]

I'm not sure applied function decorators are really of a huge interest to the API user. Decorators are supposed to be rather transparent in how they modify the underlying function — the function's basic properties should not change in an incompatible way. Thus I view decorators as more of an implementation detail of interest to the core developers, rather than the API end users. I guess it's a spectrum.

I'm up for pdoc.Function.decorators() returning a list of pdoc.Function/pdoc.Class/pdoc.External objects (provided it can be done — some decorators set __wrapped__, some don't). This can, then, be enumerated in the template similar to how MRO ancestors are:

pdoc/pdoc/templates/html.mako

Lines 197 to 204 in d9df475

	% if mro:
	<h3>Ancestors</h3>
	<ul class="hlist">
	% for cls in mro:
	<li>${link(cls)}</li>
	% endfor
	</ul>
	%endif

all subject to a new config.mako setting show_decorators = False.