[Bug] [DOC501 & DOC502] Numpy still docstrings with `:exc:` directive for exceptions are falsely flagged

[AbstractUmbra]

Intro

Searched keywords: DOC501, DOC502, numpy exception
Command invoked: ruff check project/utils.py
Ruff config:-

pyproject.toml excerpt

[tool.ruff]
line-length = 125
target-version = "py311"

[tool.ruff.lint]
select = [
    "A",
    "ANN",
    "ASYNC",
    "B",
    "BLE",
    "C4",
    "COM",
    "DOC",
    "DTZ",
    "E",
    "EM",
    "ERA",
    "F",
    "FA",
    "FBT",
    "FURB",
    "G",
    "I",
    "INP",
    "ISC",
    "NPY",
    "PD",
    "PERF",
    "PGH",
    "PIE",
    "PLC",
    "PLE",
    "PLW",
    "PTH",
    "PYI",
    "Q",
    "Q003",
    "RET",
    "RSE",
    "RUF",
    "S",
    "SIM",
    "SLOT",
    "T20",
    "TC",
    "TID",
    "TRY",
    "UP",
    "YTT",
]
ignore = [
    "ANN401",
    "F401",
    "F402",
    "F403",
    "F405",
    "PD011",   # this is not a numpy codebase
    "PERF203",
    "PLC0414", # pyright ruling for `as` imports needed
    "Q000",
    "RUF001",
    "RUF009",
    "SIM105",
    "TRY003",  # over-eager rule
    "TRY301",  # unrealistic rule
    "UP034",
    "UP038",
]
unfixable = [
    "E501", # line length handled in other ways by ruff format
    "ERA",  # Don't delete commented out code
]
[tool.ruff.lint.per-file-ignores]
"tests/*" = [
    "S101",   # we use `assert` in tests
    "EM101",  # testing exceptions are okay I feel
    "INP001", # we don't import tests generally
]

[tool.ruff.format]
# Like Black, use double quotes for strings.
quote-style = "double"
# Like Black, indent with spaces, rather than tabs.
indent-style = "space"
# Like Black, respect magic trailing commas.
skip-magic-trailing-comma = false
# Like Black, automatically detect the appropriate line ending.
line-ending = "auto"

[tool.ruff.lint.isort]
split-on-trailing-comma = true
combine-as-imports = true

[tool.ruff.lint.pydocstyle]
convention = "numpy"

[tool.ruff.lint.flake8-annotations]
allow-star-arg-any = true

[tool.ruff.lint.flake8-pytest-style]
fixture-parentheses = false
mark-parentheses = false
parametrize-names-type = "csv"

[tool.ruff.lint.flake8-quotes]
inline-quotes = "double"

[tool.ruff.lint.flake8-tidy-imports.banned-api]
# https://discuss.python.org/t/problems-with-typeis/55410/6
# https://discuss.python.org/t/problems-with-typeis/55410/46
# Until what can go into a TypeIs/TypeGuard changes, these are just dangerous.
"typing.TypeIs".msg = "TypeIs is fundamentally unsafe, even when using it as described to be safe"
"typing.TypeGuard".msg = "TypeGuard is fundamentally unsafe"
"typing_extensions.TypeIs".msg = "TypeIs is fundamentally unsafe, even when using it as described to be safe"
"typing_extensions.TypeGuard".msg = "TypeGuard is fundamentally unsafe"

Ruff version:-

❯ ruff --version             
ruff 0.8.0

Problem

When using the numpy style of docstrings, I tend to use the :exc: role for my documentation generation using Sphinx, this however is falsely flagged under the above two rules. I was wondering if this could be accounted for in the rule checking?

Reproducible code

Code

def foo() -> None:
    """Testing method.

    Raises
    -------
    :exc:`RuntimeError`
    """
    raise RuntimeError

Output

❯ ruff check project/test.py --preview
project/test.py:2:5: DOC501 Raised exception `RuntimeError` missing from docstring
  |
1 |   def foo() -> None:
2 |       """Testing method.
  |  _____^
3 | | 
4 | |     Raises
5 | |     -------
6 | |     :exc:`RuntimeError`
7 | |     """
  | |_______^ DOC501
8 |       raise RuntimeError
  |
  = help: Add `RuntimeError` to the docstring

project/test.py:2:5: DOC502 Raised exception is not explicitly raised: `:exc:`RuntimeError``
  |
1 |   def foo() -> None:
2 |       """Testing method.
  |  _____^
3 | | 
4 | |     Raises
5 | |     -------
6 | |     :exc:`RuntimeError`
7 | |     """
  | |_______^ DOC502
8 |       raise RuntimeError
  |
  = help: Remove `:exc:`RuntimeError`` from the docstring

Found 2 errors.

[MichaReiser]

I believe this is the same as #12520

[AbstractUmbra]

I believe this is the same as #12520

I did see this issue and I believe since this relates to Sphinx style docstrings, not Numpy still that they are different.
As this issue also links to the larger issue to track the implementation of pydoclint, in which it has a checkbox next to the numpy implementation.

[MichaReiser]

Ah sorry, I misread your description. I assumed you use the sphinx style instead of you using sphinx to generate the documentation

Do you have a link documenting that :exc: is a valid role? I couldn't find it in the numpy docstring documentation

[AbstractUmbra]

It is not very well published, but it is found here.

[MichaReiser]

Hmm okay, but that's sphinx after all? It doesn't seem to be part of the official numpy guide?

[AbstractUmbra]

Oh I guess that would be correct then.
It's numpy style strings but using Sphinx directives and roles, my mistake. It is a duplicate of the earlier issue!

[MichaReiser]

I'll merge this issue into the existing issue.