pdoc
pdoc copied to clipboard
Generate links to class members for backticks in docstrings within that class
Expected Behavior
Within a class-level docstring (or even better also any docstring in a class method), class method names in backticks should generate links to that method.
Actual Behavior
The link is only generated if the member name is qualified with the class name. method
will not produce a link, but MyClass.method
will. This not only requires extra typing but produces overly verbose and therefore harder-to-parse link text.
Steps to Reproduce
class MyClass(object):
""" This is a complicated class.
Users in general will only ever need to use the `doeverything` method.
Here's a link for it: `MyClass.doeverything`
"""
def __init__(self):
pass
def doeverything(self):
""" do all the things """
print("I'm doing everything!")
Additional info
- pdoc version: 0.8.1
It introduces ambiguities such as:
def foo(): pass
class C:
def foo():
"""Reference `foo` — Which?"""
I'm somewhat :+1: That would be nice and handy. A similar ambiguity already exists when ref'ing module names, and only the current one can be overcome by demanding use of fully-qualified names (pdoc.Doc.refname
) in those cases.
However, the current architecture only passes module
around (precisely for linking)
https://github.com/pdoc3/pdoc/blob/004204320773cb98a8f0cd5fa82e8095f517e488/pdoc/templates/html.mako#L17-L18
and only pdoc.Module
provide documentation object discovery from string name.
I'm not too fond to add to complexity there. Perhaps if someone can propose to reduce it?
A rule for resolving ambiguities could be that unqualified function names in backticks refer to the namespace that is closest (from inside to outside) to the docstring . In the example by @kernc 'Reference foo
' would refer to the class method itself. If it should refer to the global function it needs to be quilified by the module name like this 'Reference module.foo
.