pdoc icon indicating copy to clipboard operation
pdoc copied to clipboard

Generate links to class members for backticks in docstrings within that class

Open bloer opened this issue 4 years ago • 2 comments

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

bloer avatar Apr 22 '20 20:04 bloer

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?

kernc avatar Apr 22 '20 22:04 kernc

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.

janscience avatar Sep 09 '20 21:09 janscience