pdoc3 / pdoc3/pdoc

Upgrade code reference warnings to errors.

Open
#420 1 comment 2 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

bug enhancement good first issue Hacktoberfest help wanted 🤷
Dominant language
Python
Stars
1.2k
Forks
146
PR merge metrics
No merged PRs in 30d

Description

Expected Behavior

I don't know if it's "expected" behavior per say, of feature/change request.

I'd like a way to have ReferenceWarning: Code reference mymodule.erroneous_reference in module "mymodule" does not match any documented object. be an error, so that my CI action catches this sort of problem.

Currently, it seems only import errors are considered "errors", as per --skip-error. I would expect that erroneous references should be errors as well, that can be downgraded to warning using --skip-error.

I can do a quick PR if that's ok with you :)

Actual Behavior
def test() -> "mymodule.erroneous_reference":
  pass

or

def test():
    """Hello world

    Returns:
        mymodule.erroneous_reference
    """
    pass

gives ReferenceWarning: Code reference mymodule.erroneous_reference in module "mymodule" does not match any documented object.

which is a warning, regardless if skip-errors is set.

Steps to Reproduce
def test() -> "mymodule.erroneous_reference":
  pass
Additional info
  • pdoc version: latest, master

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

Search for ReferenceWarning and the --skip-error handling, then reproduce the issue with the annotated return type or docstring examples. Done means erroneous code references are treated as errors by default and can be downgraded to warnings with --skip-error.

Written by the indexing model from the issue text.

Assessment

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

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.