pdoc3 / pdoc3/pdoc

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

Open
#188 2 comments 0 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

enhancement
Dominant language
Python
Stars
1.2k
Forks
146
PR merge metrics
No merged PRs in 30d

Description

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

Contributor guide

Open the contributing guide

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

Research direction

Start by reproducing the documented example with pdoc 0.8.1, comparing doeverything with MyClass.doeverything inside a class docstring. Trace the docstring reference-resolution entry point and identify how the containing class is available. Done means an unqualified backticked class member generates a link while preserving the short link text.

Written by the indexing model from the issue text.

Assessment

Tech stack
python
Domain
documentation
Issue type
Bug
Difficulty
3/5
Estimated time
1-2 days
Activity status
Stale
Clarity
Mostly clear
Newbie friendliness
45/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.